Interfaces#
toop_engine_interfaces
#
toop_engine_interfaces.folder_structure
#
Defines constants for the folder structure.
File: folder_structure.py Author: Benjamin Petrick Created: 2024-09-12
PREPROCESSING_PATHS
module-attribute
#
PREPROCESSING_PATHS = {
"grid_file_path_powsybl": "grid.xiidm",
"grid_file_path_pandapower": "grid.json",
"network_data_file_path": "network_data.pkl",
"masks_path": "masks",
"static_information_file_path": "static_information.hdf5",
"importer_auxiliary_file_path": "importer_auxiliary_data.json",
"initial_topology_path": "initial_topology",
"LF_CA_path": "initial_topology/LF_CA",
"single_line_diagram_path": "initial_topology/single_line_diagram",
"asset_topology_file_path": "initial_topology/asset_topology.json",
"original_gridfile_path": "initial_topology/original_gridfile",
"logs_path": "logs",
"start_datetime_info_file_path": "logs/start_datetime.info",
"chronics_path": "chronics",
"action_set_file_path": "action_set.json",
"nminus1_definition_file_path": "nminus1_definition.json",
"ignore_file_path": "ignore_elements.csv",
"contingency_list_file_path": "contingency_list.csv",
"static_information_stats_file_path": "static_information_stats.json",
}
POSTPROCESSING_PATHS
module-attribute
#
POSTPROCESSING_PATHS = {
"optimizer_snapshots_path": "optimizer_snapshots",
"dc_optimizer_snapshots_path": "optimizer_snapshots/dc",
"ac_optimizer_snapshots_path": "optimizer_snapshots/ac",
"dc_plus_optimizer_snapshots_path": "optimizer_snapshots/dc_plus",
"LF_CA_ac_path": "optimizer_snapshots/ac/LF_CA",
"single_line_diagram_ac_path": "optimizer_snapshots/ac/single_line_diagram",
"logs_path": "logs",
}
NETWORK_MASK_NAMES
module-attribute
#
NETWORK_MASK_NAMES = {
"relevant_subs": "relevant_subs.npy",
"line_for_nminus1": "line_for_nminus1.npy",
"line_for_reward": "line_for_reward.npy",
"line_overload_weight": "line_overload_weight.npy",
"line_disconnectable": "line_disconnectable.npy",
"line_tso_border": "line_tso_border.npy",
"line_blacklisted": "line_blacklisted.npy",
"trafo_for_nminus1": "trafo_for_nminus1.npy",
"trafo_for_reward": "trafo_for_reward.npy",
"trafo_overload_weight": "trafo_overload_weight.npy",
"trafo_disconnectable": "trafo_disconnectable.npy",
"trafo_dso_border": "trafo_dso_border.npy",
"trafo_n0_n1_max_diff_factor": "trafo_n0_n1_max_diff_factor.npy",
"trafo_blacklisted": "trafo_blacklisted.npy",
"trafo_pst_controllable": "trafo_pst_controllable.npy",
"trafo3w_for_nminus1": "trafo3w_for_nminus1.npy",
"trafo3w_for_reward": "trafo3w_for_reward.npy",
"trafo3w_overload_weight": "trafo3w_overload_weight.npy",
"trafo3w_disconnectable": "trafo3w_disconnectable.npy",
"trafo3w_n0_n1_max_diff_factor": "trafo3w_n0_n1_max_diff_factor.npy",
"tie_line_for_reward": "tie_line_for_reward.npy",
"tie_line_for_nminus1": "tie_line_for_nminus1.npy",
"tie_line_overload_weight": "tie_line_overload_weight.npy",
"tie_line_disconnectable": "tie_line_disconnectable.npy",
"tie_line_tso_border": "tie_line_tso_border.npy",
"dangling_line_for_nminus1": "dangling_line_for_nminus1.npy",
"generator_for_nminus1": "generator_for_nminus1.npy",
"load_for_nminus1": "load_for_nminus1.npy",
"switch_for_nminus1": "switch_for_nminus1.npy",
"switch_for_reward": "switch_for_reward.npy",
"cross_coupler_limits": "cross_coupler_limits.npy",
"sgen_for_nminus1": "sgen_for_nminus1.npy",
"busbar_for_nminus1": "busbar_for_nminus1.npy",
}
OUTPUT_FILE_NAMES
module-attribute
#
OUTPUT_FILE_NAMES = {
"multiple_topologies": "repertoire.json",
"realized_asset_topology": "asset_topology.json",
"postprocessed_topology": "topology.json",
"loadflows_ac": "loadflows_ac.hdf5",
"loadflows_dc": "loadflows_dc.hdf5",
"loadflows_ac_cross_coupler": "loadflows_ac_cross_coupler.hdf5",
"loadflows_dc_cross_coupler": "loadflows_dc_cross_coupler.hdf5",
}
CHRONICS_FILE_NAMES
module-attribute
#
CHRONICS_FILE_NAMES = {
"load_p": "load_p.npy",
"gen_p": "gen_p.npy",
"sgen_p": "sgen_p.npy",
"dcline_p": "dcline_p.npy",
}
toop_engine_interfaces.backend
#
The abstract interface definition for accessing data from pandapower/powerfactory/...
BackendInterface
#
Bases: ABC
Interface for the backend.
The task of this interface is to provide routines for accessing data from the grid modelling software (pandapower/powerfactory/...)
Specifically not task of this interface is to perform any validations or processing of the data
This assume a node-branch model, hence busbars would be nodes and lines, trafos, etc would be branches. Injections inject onto a node and represent both generators, loads, sgens, ...
get_ptdf
#
Get the PTDF matrix, if it was computed already
For the relevant substations it is important that only node A is given as a column in the reference topology. This is to ensure node A and B are treated properly by the algorithm.
If None is returned, the PTDF matrix will be computed by the solver based on from_node, to_node and susceptance.
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_branch n_node']
|
The unextended PTDF matrix, not including second nodes for the relevant substations, and not including the PSDF. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_psdf
#
Get the PSDF matrix, if it was computed already
If None is returned, the PSDF matrix will be computed by the solver based on shift_angle and susceptance.
This refers to the already reduced PSDF matrix, i.e. without elements that will never have a shift angle. See get_phase_shifters for more information.
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_branch n_phaseshifters']
|
The PSDF matrix, not including the PTDF. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_slack
abstractmethod
#
Get the index of the slack node
Note that the solver does not support distributed slack nodes, if you have a distributed slack, replace all but one slack node by their injections or create a virtual slack node that is connected with same-impendance lines to the other slack nodes.
| RETURNS | DESCRIPTION |
|---|---|
int
|
The index of the slack node |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_ac_dc_mismatch
#
Get the AC-DC mismatch for each branch
This is the difference between the AC and DC flow on each branch, i.e. the difference between the AC and DC loadflow results.
This is used in the solver to adjust the DC flow to match the AC flow in the N-0 case. If all zeros are returned, the solver will return pure DC flows.
Positive values mean the AC flow is higher than the DC flow, negative values mean the AC flow is lower than the DC flow.
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_timestep n_branch']
|
The AC-DC mismatch for each branch and per timestep |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_max_mw_flows
abstractmethod
#
Get the maximum flow per branch
The timestep dimension is added to represent temperature-dependent capacity limits. If the capacity limits are not temperature-dependent, the same value should be returned for all timesteps.
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_timestep n_branch']
|
The maximum flow per branch and per timestep |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_max_mw_flows_n_1
#
Get a varying max flow for N-1 if there is a difference or NaN.
In some circumstances, a higher N-1 load is allowed than N-0 as N-1 leaves some time to address an overload in practice - a line won't melt right away if it's overloaded for a few seconds until the operators can react.
If not overloaded, returns all NaNs and hence the values from get_max_mw_flows will be used.
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_timestep n_branch']
|
The maximum flow per branch and per timestep if overridden, else NaN |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_overload_weights
#
Get a factor that the overloads are multiplied with for each branch
This can be used to penalize overloads on certain branches more than on others.
If this funcion is not overloaded, returns all ones.
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_branch']
|
The overload weights for each branch |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_n0_n1_max_diff_factors
#
Get limits for the relative difference between N-0 and N-1 flows.
This is an array of factors to the base case flows. Negative factors or NaN values mean the branch will be ignored and always have a penalty of 0. For example if a branch has a 20 MW diff between N-0 and N-1 in the base case (in the unsplit configuration) and the factor is 2, then the maximum allowed diff for the n0_n1_delta penalty would be 40 MW. If a negative factor is used, this branch has no N-0 to N-1 maximum delta and will always incur a penalty of 0. See dc_solver.jax.aggregate_results.compute_n0_n1_max_diff for how these factors are used
If this function is not overloaded, returns all minus ones (i.e. no branch has a limit).
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_cross_coupler_limits
#
Get the cross-coupler limits for each relevant substation.
Returns over all buses to match conventions and if relevant substations are modified independently of the cross-coupler limits.
The limits are a P[MW] Value for each coupler.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_susceptances
abstractmethod
#
Get the susceptances of the branches
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_branch']
|
The susceptances of the branches |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_from_nodes
abstractmethod
#
Get the from nodes of the branches
| RETURNS | DESCRIPTION |
|---|---|
Int[ndarray, ' n_branch']
|
The from nodes of the branches |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_to_nodes
abstractmethod
#
Get the to nodes of the branches
| RETURNS | DESCRIPTION |
|---|---|
Int[ndarray, ' n_branch']
|
The to nodes of the branches |
get_controllable_pst_node_mask
#
Get the mask of controllable phase shifters over nodes
True means a node is (bogus node and) a controllable phase shifter, i.e. is connected to a branch that is a controllable phase shifter. False means it normal node.
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_node']
|
The mask of controllable phase shifters over nodes |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_shift_angles
abstractmethod
#
Get the shift angles of the branches in degree
The timestep dimension is added to represent time-varying phase shift angles. If the phase shift angles are not time-varying, the same value should be returned for all timesteps.
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_timestep n_branch']
|
The shift angles of the branches |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_phase_shift_mask
abstractmethod
#
Get the mask of phase shifters
True means a branch is a phase shifter, i.e. can have shift_degree != 0 False means it is not a phase shifter. Note that the controllable phase shifters are a subset of this, i.e. not every phase shifter is controllable.
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_branch']
|
The mask of phase shifters |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_controllable_phase_shift_mask
#
Which of the phase shifters are controllable
This must be a subset of get_phase_shift_mask()
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_branch']
|
The mask of controllable phase shifters |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_phase_shift_taps
#
Return the possible tap positions of each controllable PST.
The outer list has as many entries as there are controllable PSTs (see controllable_phase_shift_mask). The inner np array has as many entries as there are taps for the given PST with each value representing the angle shift for the given tap position. The taps are ordered smallest to largest angle shift. Each controllable PST must have at least one tap position.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_phase_shift_starting_taps
#
Get the starting tap position for each controllable PST, given as an integer index into pst_tap_values.
Note that taps in the original grid model might not start at zero, while in our optimization we assume taps to always be zero terminated. To translate back into original grid model, add get_phase_shift_low_taps.
The outer list has as many entries as there are controllable PSTs (see controllable_phase_shift_mask). The inner np array has as many entries as there are taps for the given PST with each value representing the angle shift for the given tap position. The taps are ordered smallest to largest angle shift.
If this function is not overloaded, it is assumed that all controllable PSTs start at their lowest tap position (i.e. index 0).
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_phase_shift_low_taps
#
Get the lowest tap position in the original grid model
Original taps are needed so taps as integer indices into tap values can be converted back to the original tap positions by tap + low_tap
If this function is not overloaded, it is assumed that all controllable PSTs have a low tap of 0.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_relevant_node_mask
abstractmethod
#
Get true if a node is part of the relevant nodes
This refers to the node A (the node that is present in the un-extended PTDF) of the relevant substations. The relevant nodes are those that can be split later on in the solver.
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_node']
|
The mask over nodes, indicating if they are relevant (splittable) |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_monitored_branch_mask
abstractmethod
#
Get the mask of monitored branches for the reward calculation
True means a branch is monitored, False means it is not monitored
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_branch']
|
The mask of monitored branches |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_branches_in_maintenance
abstractmethod
#
Get the mask of branches in maintenance
True means a branch is in maintenance, False means it is not in maintenance
The timestep dimension is added to represent time-varying maintenance schedules. If the maintenance schedules are not time-varying, the same value should be returned for all timesteps.
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_timestep n_branch']
|
The mask of branches in maintenance |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_disconnectable_branch_mask
abstractmethod
#
Get the mask of disconnectable branches
True means a branch is disconnectable as a remedial action, False means it must stay online
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_branch']
|
The mask of disconnectable branches |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_outaged_branch_mask
abstractmethod
#
Get the mask of outaged branches for the N-1 computation
True means a branch is outaged, False means it is not outaged
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_branch']
|
The mask of outaged branches |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_outaged_injection_mask
abstractmethod
#
Get the mask of outaged injections for the N-1 computation
True means an injection is outaged, False means it is not outaged
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_injection']
|
The mask of outaged injections |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_multi_outage_branches
abstractmethod
#
Get the mask of outaged branches for potential multi-outages
True means a branch is outaged, False means it is not outaged.
get_multi_outage_branches, get_multi_outage_nodes and get_multi_outage_names have to return the same first dimension, i.e. the same number of multi-outages.
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_multi_outages n_branch']
|
The mask of outaged branches for every multi-outage |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_multi_outage_nodes
abstractmethod
#
Get the mask of outaged nodes for potential multi-outages
True means a node is outaged, False means it is not outaged.
get_multi_outage_branches, get_multi_outage_nodes and get_multi_outage_names have to return the same first dimension, i.e. the same number of multi-outages.
| RETURNS | DESCRIPTION |
|---|---|
Bool[ndarray, ' n_multi_outages n_node']
|
The mask of outaged nodes for every multi-outage |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_injection_nodes
abstractmethod
#
Get the node index of the injections
| RETURNS | DESCRIPTION |
|---|---|
Int[ndarray, ' n_injection']
|
The node index that the injection injects onto |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_mw_injections
abstractmethod
#
Get the MW injections of the injections
The timestep dimension is added to represent time-varying injections. If the injections are not time-varying, the same value should be returned for all timesteps.
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_timestep n_injection']
|
The MW injections of the injections |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_base_mva
abstractmethod
#
Get the baseMVA of the grid
| RETURNS | DESCRIPTION |
|---|---|
float
|
The base MVA of the grid |
get_asset_topology
#
Get the asset topology of the grid.
If given, the asset topology for the grid can be returned, describing more information about the physical layout of the stations
| RETURNS | DESCRIPTION |
|---|---|
Optional[Topology]
|
The asset topology of the grid |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_node_ids
abstractmethod
#
Get the ids of the nodes as a Sequence of length N_node
| RETURNS | DESCRIPTION |
|---|---|
Union[Sequence[str], Sequence[int]]
|
The ids of the nodes |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_branch_ids
abstractmethod
#
Get the ids of the branches as a Sequence of length N_branch
| RETURNS | DESCRIPTION |
|---|---|
Union[Sequence[str], Sequence[int]]
|
The ids of the branches |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_injection_ids
abstractmethod
#
Get the ids of the injections as a Sequence of length N_injection
| RETURNS | DESCRIPTION |
|---|---|
Union[Sequence[str], Sequence[int]]
|
The ids of the injections |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_multi_outage_ids
abstractmethod
#
Get the ids of the multi-outages as a Sequence of length N_multi_outages
| RETURNS | DESCRIPTION |
|---|---|
Union[Sequence[str], Sequence[int]]
|
The ids of the multi-outages |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_node_names
abstractmethod
#
Get the names of the nodes as a Sequence of length N_node
| RETURNS | DESCRIPTION |
|---|---|
Sequence[str]
|
The names of the nodes |
get_branch_names
abstractmethod
#
Get the names of the branches as a Sequence of length N_branch
| RETURNS | DESCRIPTION |
|---|---|
Sequence[str]
|
The names of the branches |
get_injection_names
abstractmethod
#
Get the names of the injections
| RETURNS | DESCRIPTION |
|---|---|
Sequence[str]
|
The names of the injections |
get_multi_outage_names
abstractmethod
#
Get the names of the multi-outages as a Sequence of length N_multi_outages
If more than one element are involved in a multi-outage you can return a concatenated name
| RETURNS | DESCRIPTION |
|---|---|
Sequence[str]
|
The names of the multi-outages |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_branch_types
abstractmethod
#
Get the type of the branches
| RETURNS | DESCRIPTION |
|---|---|
Sequence[str]
|
The type of the branches |
get_node_types
abstractmethod
#
Get the type of the nodes
| RETURNS | DESCRIPTION |
|---|---|
Sequence[str]
|
The type of the nodes |
get_injection_types
abstractmethod
#
Get the type of the injections
| RETURNS | DESCRIPTION |
|---|---|
Sequence[str]
|
The type of the injections |
get_multi_outage_types
abstractmethod
#
Get the type of the multi-outages as a Sequence of length N_multi_outages
| RETURNS | DESCRIPTION |
|---|---|
Sequence[str]
|
The type of the multi-outages |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_metadata
abstractmethod
#
Can be used to return metadata or additional information about the grid.
This is not used by the solver but rather to easy postprocessing and validation. You can return an empty dict if you don't want to use this field.
| RETURNS | DESCRIPTION |
|---|---|
dict
|
The metadata of the grid |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
get_busbar_outage_map
#
Get the mapping of stations to busbars for the busbar-outages
The key of the dict is the station's grid_model_id and the value is a list of grid_mdoel_ids of the busbars that have to be outaged. If this method is not overloaded, all the physical busbars of the relevant stations will be outaged.
| RETURNS | DESCRIPTION |
|---|---|
Optional[dict[str, Sequence[str]]]
|
The mapping of busbar-outages to the relevant nodes |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/backend.py
toop_engine_interfaces.types
#
Define global type aliases.
Currently this holds only the MetricType, a Literal of all possible metrics.
The meaning of the metrics is documented in metrics.md in the docs folder.
MatrixMetric
module-attribute
#
MatrixMetric = Literal[
"max_flow_n_0",
"median_flow_n_0",
"overload_energy_n_0",
"underload_energy_n_0",
"overload_energy_limited_n_0",
"exponential_overload_energy_n_0",
"exponential_overload_energy_limited_n_0",
"critical_branch_count_n_0",
"critical_branch_count_limited_n_0",
"max_flow_n_1",
"median_flow_n_1",
"overload_energy_n_1",
"underload_energy_n_1",
"overload_energy_limited_n_1",
"exponential_overload_energy_n_1",
"exponential_overload_energy_limited_n_1",
"critical_branch_count_n_1",
"critical_branch_count_limited_n_1",
"top_k_overloads_n_1",
"cumulative_overload_n_0",
"cumulative_overload_n_1",
]
OperationMetric
module-attribute
#
OtherMetric
module-attribute
#
OtherMetric = Literal[
"n0_n1_delta",
"cross_coupler_flow",
"n_2_penalty",
"bb_outage_penalty",
"bb_outage_overload",
"bb_outage_grid_splits",
"max_va_across_coupler",
"max_va_diff_n_0",
"max_va_diff_n_1",
"overload_current_n_0",
"overload_current_n_1",
"non_converging_loadflows",
"fitness_dc",
]
toop_engine_interfaces.stored_action_set
#
Holds a format for storing the action set for later use in postprocessing.
This is different from the jax-internal action set as defined in jax/types.py where only jax-relevant information is stored, but is instead aimed at use in postprocessing and visualization. Instead of just storing the electrical switching state, this bases on the asset topology to store physical switchings to make a translation to .dgs or other formats easier.
One of the decisions to take was was whether to use a single action set for all timesteps or a different one for each timestep. As the jax part currently also only supports one action set for all timesteps, we decide to mirror this for the time being, i.e. we do not store strategies but topologies in the action set.
Furthermore, it should also be possible to use a global action set if necessary. Meaning, by default an action is substation-local, but it it can span multiple substations as well. Using a format that is suitable for both options is desirable for easier collaboration.
Another question was whether to store the switching distance and busbar information in the action set, but the switching distance can be trivially recomputed by using the station_diff between the starting topology and the station in the action set. BB outage information can also be retrieved from the asset topology.
There is a slim hope of storing the action set independent of the grid state but based on the master grid, however right now there is a fundamental way that 'binds' an action set to the specific grid it has been computed on: During the enumerations, all electrical actions are enumerated and then physical realizations are found for it based on heuristics. These heuristics take the grid state into account, so it could be that an electrical action can not be realized the same way if maintenances are active. Hence, for the moment, it is no problem to tie the initial topology into the action set.
PSTRange
#
Bases: GridElement
Phase shifting transformers can be set within the scope of non-costly optimization.
A PST has a list of taps, each with an angle shift.
starting_tap
instance-attribute
#
The tap the PST was set to before optimization. To filter out actions that do not change anything in the UI, this is required.
id
instance-attribute
#
The id of the element. For powsybl grids this is the global string id, for pandapower this is the integer index into the dataframe
name
class-attribute
instance-attribute
#
The name of the element. This is optional, but can be used to provide a more human-readable name for the element.
type
instance-attribute
#
For pandapower, we need to further specify a type which corresponds to the table pandapower stores the information in. Valid tables are 'line', 'trafo', 'ext_grid', 'gen', 'load', 'shunt', ... For powsybl, this is not strictly needed to identify the element however it makes it easier. In that case, type will be something like TIE_LINE, LINE, TWO_WINDING_TRANSFORMER, GENERATOR, etc.
kind
instance-attribute
#
The kind of the element. Usually these are handled differently in the grid modelling software, so it can make assembling an N-1 analysis easier if it is known if the element is a branch, bus or injection. This could be inferred from the type, however for conveniece it is stored separately.
For the bus type there is some potential confusion in powsybl. In pandapower, this always refers to the net.bus df. In powsybl in a bus/branch model, there are no busbar sections in powsybl, i.e. net.get_node_breaker_topology does not deliver busbar sections. Meaning, the "bus" type refers to the net.get_bus_breaker_topology buses if it's a bus/breaker topology bus. If it's a node/breaker topology, then "bus" refers to the busbar section.
HVDCRange
#
Bases: GridElement
High voltage direct current lines can be set within the scope of non-costly optimization.
An HVDC has a minimum and maximum power setpoint
id
instance-attribute
#
The id of the element. For powsybl grids this is the global string id, for pandapower this is the integer index into the dataframe
name
class-attribute
instance-attribute
#
The name of the element. This is optional, but can be used to provide a more human-readable name for the element.
type
instance-attribute
#
For pandapower, we need to further specify a type which corresponds to the table pandapower stores the information in. Valid tables are 'line', 'trafo', 'ext_grid', 'gen', 'load', 'shunt', ... For powsybl, this is not strictly needed to identify the element however it makes it easier. In that case, type will be something like TIE_LINE, LINE, TWO_WINDING_TRANSFORMER, GENERATOR, etc.
kind
instance-attribute
#
The kind of the element. Usually these are handled differently in the grid modelling software, so it can make assembling an N-1 analysis easier if it is known if the element is a branch, bus or injection. This could be inferred from the type, however for conveniece it is stored separately.
For the bus type there is some potential confusion in powsybl. In pandapower, this always refers to the net.bus df. In powsybl in a bus/branch model, there are no busbar sections in powsybl, i.e. net.get_node_breaker_topology does not deliver busbar sections. Meaning, the "bus" type refers to the net.get_bus_breaker_topology buses if it's a bus/breaker topology bus. If it's a node/breaker topology, then "bus" refers to the busbar section.
ActionSet
#
Bases: BaseModel
A collection of actions in the form of asset topology stations.
We make a convention that the beginning of the action set always includes substation local actions and the global actions are at the end.
starting_topology
instance-attribute
#
How the grid looked like when the action set was first generated.
connectable_branches
instance-attribute
#
A list of assets that can be connected as a remedial action.
disconnectable_branches
instance-attribute
#
A list of assets that can be disconnected as a remedial action. Currently the DC solver supports only branches.
pst_ranges
instance-attribute
#
A list of phase shifting transformers that can be set as a remedial action.
hvdc_ranges
instance-attribute
#
A list of high voltage direct current lines that can be set as a remedial action. This is currently not implemented yet in the solver.
local_actions
instance-attribute
#
A list of split/reconfiguration actions that affect exactly one substation.
global_actions
instance-attribute
#
A list of split/reconfiguration actions that affect multiple substations. Each action contains a list of affected stations.
load_action_set_fs
#
Load an action set from a file system.
| PARAMETER | DESCRIPTION |
|---|---|
filesystem
|
The file system to use to load the action set.
TYPE:
|
file_path
|
The path to the file containing the action set in json format.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ActionSet
|
The action set loaded from the file. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/stored_action_set.py
load_action_set
#
Load an action set from a file.
| PARAMETER | DESCRIPTION |
|---|---|
file_path
|
The path to the file containing the action set in json format.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ActionSet
|
The action set loaded from the file. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/stored_action_set.py
save_action_set
#
Save an action set to a file.
| PARAMETER | DESCRIPTION |
|---|---|
file_path
|
The path to the file to save the action set to in json format.
TYPE:
|
action_set
|
The action set to save.
TYPE:
|
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/stored_action_set.py
random_actions
#
Generate a random topology from the action set.
Makes sure to sample each substation at most once.
| PARAMETER | DESCRIPTION |
|---|---|
action_set
|
The action set to generate the random topology from.
TYPE:
|
rng
|
The random number generator to use.
TYPE:
|
n_split_subs
|
The number of substations to split. If this is more than total number of substations, all substations are split. (i.e. will be clipped to the number of substations)
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[int]
|
A list of indices of the action set with substations to split. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/stored_action_set.py
Messages#
toop_engine_interfaces.messages.preprocess
#
toop_engine_interfaces.messages.lf_service
#
toop_engine_interfaces.messages.lf_service.loadflow_commands
#
Describes the interfaces for a loadflow service providing N-1 computations in AC or DC to customers.
The communication follows a 2 step pattern:
- Grid load - Load a grid file into the engine and potentially perform some preprocessing. The engine should return a grid reference upon this call, which is used in the job to reference the grid. Multiple grids can be loaded at the same time, it is the responsibility of the engine to perform memory management (i.e. swap out a grid to disk if memory is full).
- Execute jobs - Run a loadflow job on the engine. The job references the grid that was loaded in step 2. A call to this can contain multiple jobs, allowing the engine to parallelize over jobs in addition to parallelizing over timesteps/outages.
The LoadflowEngine protocol describes this two step process in detail.
BaseFilter
#
Bases: BaseModel, ABC
A base class for filters.
The idea behind filters is to implement logics that can not be implemented with the monitored elements directly but that are dependent on the loadflow results
This is not to be used directly, but to be subclassed.
WorstContingencyBranchFilter
#
Bases: BaseFilter
If this filter is applied, it will reduce the branch results to only the worst N-1 case/side per branch and timestep.
Worst is determined with respect to the loading value. Branches that don't have a rating will never be returned.
If there are multiple worst N-1 cases/sides that produce a tie, one will be chosen at random. This filtering happens on a per-timestep basis, meaning for every timestep there should be as many results as monitored branches, but they can refer to different N-1 cases.
VoltageBandFilter
#
Bases: BaseFilter
If this filter is applied, it will reduce the node results to only the results that are outside of a specified band.
The band is defined by a minimum and maximum p.u. value for all nodes
return_basecase
class-attribute
instance-attribute
#
Whether to return the basecase at all times. If this is set to True, the basecase will always be returned even if it is inside the band and hence should be filtered out.
filter_type
class-attribute
instance-attribute
#
An identifier for the discriminated union
PercentCutoffBranchFilter
#
Bases: BaseFilter
Filter, if applied returns only branch results that are above a loading threshold.
Elements for which no loading could be computed (e.g. due to missing ratings) are never returned. This filtering happens on a per-timestep basis, i.e. if a branch/contingency is above the threshold in one timestep, it will be returned in exactly that timestep.
Job
#
Bases: BaseModel
A job constitutes a single workload and will produce a LoadflowResults object.
There are different types of jobs based on the workload, the simple being a base job with no changes to the base grid.
id
instance-attribute
#
A unique identifier for the job. This is used to reference the job in the results.
branch_filter
class-attribute
instance-attribute
#
Filters for the branch results table. Exactly one filter can be active per table and job
node_filter
class-attribute
instance-attribute
#
Filters for the node results table. Exactly one filter can be active per table and job
job_type
class-attribute
instance-attribute
#
An identifier for the discriminated union
timestep_subselection
class-attribute
instance-attribute
#
If this is set, only the timesteps in this list are computed. If this is not set, all timesteps are computed. Timesteps are referenced by their index in the grid file, starting at 0.
JobWithSwitchingStrategy
#
Bases: Job
A job that includes a switching strategy.
This strategy shall be applied before the loadflow computation and might alter the topology of the grid.
strategy
instance-attribute
#
The switching strategy that is to be applied before the loadflow computation
job_type
class-attribute
instance-attribute
#
An identifier for the discriminated union
id
instance-attribute
#
A unique identifier for the job. This is used to reference the job in the results.
branch_filter
class-attribute
instance-attribute
#
Filters for the branch results table. Exactly one filter can be active per table and job
node_filter
class-attribute
instance-attribute
#
Filters for the node results table. Exactly one filter can be active per table and job
timestep_subselection
class-attribute
instance-attribute
#
If this is set, only the timesteps in this list are computed. If this is not set, all timesteps are computed. Timesteps are referenced by their index in the grid file, starting at 0.
JobWithCGMESChanges
#
Bases: Job
A job that includes changes in CGMES format. This is only applicable if the grid is a CGMES grid
tp_files
instance-attribute
#
The file including the topology changes that shall be applied.
There must be as many entries as timesteps in the grid, but the same file can be referenced multiple times.
ssh_files
instance-attribute
#
The file including the state/injection changes that shall be applied.
There must be as many entries as timesteps in the grid, but the same file can be referenced multiple times.
job_type
class-attribute
instance-attribute
#
An identifier for the discriminated union
id
instance-attribute
#
A unique identifier for the job. This is used to reference the job in the results.
branch_filter
class-attribute
instance-attribute
#
Filters for the branch results table. Exactly one filter can be active per table and job
node_filter
class-attribute
instance-attribute
#
Filters for the node results table. Exactly one filter can be active per table and job
timestep_subselection
class-attribute
instance-attribute
#
If this is set, only the timesteps in this list are computed. If this is not set, all timesteps are computed. Timesteps are referenced by their index in the grid file, starting at 0.
InjectionAddition
#
Bases: BaseModel
A single addition of an injection at a node.
This feature only support PQ nodes, if attempted to apply to a branch, pv node or slack node, the engine should ignore this addition and log a warning.
Positive values shall have the same effect as sgens, i.e. power is produced, while negative values will have the same effect as loads, i.e. power is consumed.
timestep_subselection
class-attribute
instance-attribute
#
If this is given, the addition only happens in the timesteps that are in this list. If this is not given, the addition happens in all timesteps.
JobWithInjectionAdditions
#
Bases: Job
Adds a constant injection to a node in the grid.
This feature assumes all injections are added to PQ nodes - otherwise they will be ignored.
Positive values shall have the same effect as sgens, i.e. power is produced, while negative values will have the same effect as loads, i.e. power is consumed.
job_type
class-attribute
instance-attribute
#
An identifier for the discriminated union
id
instance-attribute
#
A unique identifier for the job. This is used to reference the job in the results.
branch_filter
class-attribute
instance-attribute
#
Filters for the branch results table. Exactly one filter can be active per table and job
node_filter
class-attribute
instance-attribute
#
Filters for the node results table. Exactly one filter can be active per table and job
timestep_subselection
class-attribute
instance-attribute
#
If this is set, only the timesteps in this list are computed. If this is not set, all timesteps are computed. Timesteps are referenced by their index in the grid file, starting at 0.
BaseGrid
#
Bases: BaseModel, ABC
A base class for grid files. This is not to be used directly, but to be subclassed
n_1_definition
class-attribute
instance-attribute
#
The N-1 cases that are to be computed. If this is provided, this shall overwrite the N-1 cases that are defined in the grid files if the format supports such definition. If this is not provided, the N-1 cases that are defined in the grid files shall be used. If neither is provided, the engine should throw an error.
grid_type
instance-attribute
#
An identifier for the discriminated union, to be set by the subclasses
CGMESGrid
#
Bases: BaseGrid
A CGMES grid file does not need to store much additional information
grid_files
instance-attribute
#
A list of paths to grid files. This can include multiple .tp and .ssh files which are to be interpreted as multiple timesteps. If a .tp and a .ssh file have the same filename or the same timestep metadata inside the file, they correspond to the same timestep. Timesteps should be sorted by the timestep information inside the CGMES files.
grid_type
class-attribute
instance-attribute
#
An identifier for the discriminated union
n_1_definition
class-attribute
instance-attribute
#
The N-1 cases that are to be computed. If this is provided, this shall overwrite the N-1 cases that are defined in the grid files if the format supports such definition. If this is not provided, the N-1 cases that are defined in the grid files shall be used. If neither is provided, the engine should throw an error.
UCTEGrid
#
Bases: BaseGrid
A list of UCTE files that are to be loaded into the engine
grid_files
instance-attribute
#
A list of paths to grid files. This can include multiple .ucte files which are to be interpreted as multiple timesteps. Timesteps should be interpreted in the order of this list
grid_type
class-attribute
instance-attribute
#
An identifier for the discriminated union
n_1_definition
class-attribute
instance-attribute
#
The N-1 cases that are to be computed. If this is provided, this shall overwrite the N-1 cases that are defined in the grid files if the format supports such definition. If this is not provided, the N-1 cases that are defined in the grid files shall be used. If neither is provided, the engine should throw an error.
PowsyblGrid
#
Bases: BaseGrid
A list of powsybl xiidm files that are to be loaded into the engine
grid_files
instance-attribute
#
A list of xiidm files that represent the timesteps. Timesteps should be interpreted in the order of this list
n_1_definition
class-attribute
instance-attribute
#
The N-1 cases that are to be computed. If this is provided, this shall overwrite the N-1 cases that are defined in the grid files if the format supports such definition. If this is not provided, the N-1 cases that are defined in the grid files shall be used. If neither is provided, the engine should throw an error.
PandapowerGrid
#
Bases: BaseGrid
A list of pandapower json files that are to be loaded into the engine
grid_files
instance-attribute
#
A list of pandapower files that represent the timesteps. Timesteps should be interpreted in the order of this list
n_1_definition
class-attribute
instance-attribute
#
The N-1 cases that are to be computed. If this is provided, this shall overwrite the N-1 cases that are defined in the grid files if the format supports such definition. If this is not provided, the N-1 cases that are defined in the grid files shall be used. If neither is provided, the engine should throw an error.
StartCalculationCommand
#
Bases: BaseModel
A command to run a list of jobs on the engine.
This can involve multiple N-1 computations with different changes to the base grid, but a job must share the same grid file.
loadflow_id
instance-attribute
#
A unique identifier for the loadflow run. This is used to identify the result
grid_data
class-attribute
instance-attribute
#
The string that was returned by load_grid, identifying the grid file that this job collection shall run on
method
instance-attribute
#
The method that is to be used for the loadflow computations. This can be either AC or DC. This must be the same for all jobs in the list
LoadflowEngine
#
Bases: Protocol
A protocol for a loadflow engine.
Roughly, an engine shall be able to load grids and execute jobs on them. There is some memory management that the engine needs to perform internally, i.e. it could happen that two users want to use the same engine in parallel. In that case, the engine should swap out grids to disk if memory is full.
run_job
#
Run a job on the engine.
This can involve multiple N-1 computations with different changes to the base grid, identified through multiple jobs in the BatchJob. The engine should return the results of the jobs as in-memory dataframes.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/messages/lf_service/loadflow_commands.py
ShutdownCommand
#
Bases: BaseModel
A command to shut down the preprocessing worker
toop_engine_interfaces.messages.lf_service.loadflow_heartbeat
#
Loadflow Heartbeat Commands for the kafka worker.
LoadflowStatusInfo
#
Bases: BaseModel
A status info to inform about an ongoint Loadflow solving action.
LoadflowHeartbeat
#
Bases: BaseModel
A message class for heartbeats from the loadflow worker.
When idle, this just sends a hello, and when solving it also conveys the current status of the Loadflow Analysis
toop_engine_interfaces.messages.preprocess.preprocess_results
#
Contains the result classes for the preprocessing process.
UcteImportResult
#
Bases: BaseModel
Statistics and results from an import process of UCTE data
data_folder
instance-attribute
#
The path where the entry point where the timestep data folder structure starts. The folder structure is defined in dc_solver.interfaces.folder_structure. Can be on a temp dir
n_relevant_subs
class-attribute
instance-attribute
#
The number of relevant substations
n_low_impedance_lines
class-attribute
instance-attribute
#
The number of low impedance lines that have been converted to a switch
n_branch_across_switch
class-attribute
instance-attribute
#
The number of branches across a switch that have been removed
n_line_for_nminus1
class-attribute
instance-attribute
#
The number of lines in the N-1 definition
n_line_for_reward
class-attribute
instance-attribute
#
The number of lines that are observed
n_line_disconnectable
class-attribute
instance-attribute
#
The number of lines that are disconnectable
n_trafo_for_nminus1
class-attribute
instance-attribute
#
The number of trafos in the N-1 definition
n_trafo_for_reward
class-attribute
instance-attribute
#
The number of trafos that are observed
n_trafo_disconnectable
class-attribute
instance-attribute
#
The number of trafos in the N-1 definition
n_tie_line_for_reward
class-attribute
instance-attribute
#
The number of tie lines that are observed
n_tie_line_for_nminus1
class-attribute
instance-attribute
#
The number of tie lines in the N-1 definition
n_tie_line_disconnectable
class-attribute
instance-attribute
#
The number of tie lines that are disconnectable
n_dangling_line_for_nminus1
class-attribute
instance-attribute
#
The number of dangling lines in the N-1 definition
n_generator_for_nminus1
class-attribute
instance-attribute
#
The number of generators in the N-1 definition
n_load_for_nminus1
class-attribute
instance-attribute
#
The number of loads in the N-1 definition
n_switch_for_nminus1
class-attribute
instance-attribute
#
The number of switches in the N-1 definition
n_switch_for_reward
class-attribute
instance-attribute
#
The number of switches that are observed
n_white_list
class-attribute
instance-attribute
#
The number of elements in the whitelist in total
n_white_list_applied
class-attribute
instance-attribute
#
The number of elements in the whitelist that were successfully matched and applied
n_black_list
class-attribute
instance-attribute
#
The number of elements in the blacklist in total
n_black_list_applied
class-attribute
instance-attribute
#
The number of elements in the blacklist that were successfully matched and applied
grid_type
class-attribute
instance-attribute
#
The discriminator for the ImportResult Union
StaticInformationStats
#
Bases: BaseModel
Stats about the static information class
fp_dtype
class-attribute
instance-attribute
#
A string representation of the floating point type used in the static informations, e.g. 'float32' or 'float64'.
has_double_limits
class-attribute
instance-attribute
#
Whether the static information has max_mw_flow_limited set or not
n_branches
class-attribute
instance-attribute
#
The number of branches in the PTDF matrix
n_branch_outages
class-attribute
instance-attribute
#
How many branch outages are part of the N-1 computation
n_multi_outages
class-attribute
instance-attribute
#
How many multi-outages are part of the N-1 computation
n_injection_outages
class-attribute
instance-attribute
#
How many injection outages are part of the N-1 computation
n_busbar_outages
class-attribute
instance-attribute
#
How many busbar outages are part of the N-1 computation
n_nminus1_cases
class-attribute
instance-attribute
#
How many N-1 cases are there in total
n_controllable_psts
class-attribute
instance-attribute
#
How many controllable phase shifting transformers are in the grid
n_monitored_branches
class-attribute
instance-attribute
#
How many branches are monitored
n_timesteps
class-attribute
instance-attribute
#
How many timesteps are optimized at the same time
n_relevant_subs
class-attribute
instance-attribute
#
How many relevant substations are in the grid
n_disc_branches
class-attribute
instance-attribute
#
How many disconnectable branches are in the definition
overload_energy_n0
class-attribute
instance-attribute
#
What is the N-0 overload energy of the unsplit configuration
overload_energy_n1
class-attribute
instance-attribute
#
What is the N-1 overload energy of the unsplit configuration
n_actions
class-attribute
instance-attribute
#
How many actions have been precomputed in the action set. This is the size of the branch action set, note that combinations of actions within that set are possible (product set wise) if multiple substations are split
max_station_branch_degree
class-attribute
instance-attribute
#
The maximum number of branches connected to any station in the grid
max_station_injection_degree
class-attribute
instance-attribute
#
The maximum number of injections connected to any station in the grid
mean_station_branch_degree
class-attribute
instance-attribute
#
The average number of branches connected to any station in the grid
mean_station_injection_degree
class-attribute
instance-attribute
#
The average number of injections connected to any station in the grid
reassignable_branch_assets
class-attribute
instance-attribute
#
The total number of reassignable branch assets in the grid, i.e. how many branches are connected to any of the stations
reassignable_injection_assets
class-attribute
instance-attribute
#
The total number of reassignable injection assets in the grid, i.e. how many injections are connected to any of the stations
max_reassignment_distance
class-attribute
instance-attribute
#
The maximum reassignment distance associated with any action
PowerFactoryImportResult
#
Bases: BaseModel
Statistics and results from an import process of PowerFactory data, TODO fill
grid_type
class-attribute
instance-attribute
#
The discriminator for the ImportResult Union
PreprocessingSuccessResult
#
Bases: BaseModel
Results of a preprocessing run, mainly including the static_information and network_data files.
data_folder
instance-attribute
#
The path where the entry point where the timestep data folder structure starts. The folder structure is defined in dc_solver.interfaces.folder_structure. Can be on a temp dir
initial_loadflow
instance-attribute
#
The initial AC loadflow results, i.e. the N-1 analysis without any actions applied to the grid.
initial_metrics
instance-attribute
#
The initial metrics computed for the loadflow results
static_information_stats
instance-attribute
#
Statistics about the static information file that was produced
importer_results
class-attribute
instance-attribute
#
The results of the importer process
result_type
class-attribute
instance-attribute
#
The discriminator for the Result Union
PreprocessingStartedResult
#
Bases: BaseModel
A message that is sent when the preprocessing process has started
result_type
class-attribute
instance-attribute
#
The discriminator for the Result Union
ErrorResult
#
Result
#
Bases: BaseModel
A generic class for result, holding either a successful or an unsuccessful result
preprocess_id
instance-attribute
#
The preprocess_id that was sent in the preprocess_command, used to identify the result
instance_id
class-attribute
instance-attribute
#
The instance id of the importer worker that created this result
runtime
instance-attribute
#
The runtime in seconds that the preprocessing took until the result
result
class-attribute
instance-attribute
#
The actual result data in a discriminated union
uuid
class-attribute
instance-attribute
#
A unique identifier for this result message, used to avoid duplicates during processing
timestamp
class-attribute
instance-attribute
#
When the result was sent
toop_engine_interfaces.messages.preprocess.preprocess_commands
#
Defines the commands that can be sent to a preprocessing worker.
UCTERegionType
module-attribute
#
UCTERegionType = Literal[
"A",
"B",
"C",
"D",
"D1",
"D2",
"D4",
"D6",
"D7",
"D8",
"E",
"F",
"G",
"H",
"I",
"J",
"K",
"L",
"M",
"N",
"O",
"P",
"Q",
"R",
"S",
"T",
"U",
"V",
"W",
"X",
"Y",
"Z",
"0",
"2",
"_",
]
CGMESRegionType
module-attribute
#
CGMESRegionType = Literal[
"AL",
"AD",
"AM",
"AT",
"AZ",
"BY",
"BE",
"BA",
"BG",
"HR",
"CY",
"CZ",
"DK",
"EE",
"FI",
"FR",
"GE",
"DE",
"GR",
"HU",
"IS",
"IE",
"IT",
"LV",
"LI",
"LT",
"LU",
"MT",
"MD",
"MC",
"ME",
"NL",
"MK",
"NO",
"PL",
"PT",
"RO",
"RU",
"SM",
"RS",
"SK",
"SI",
"ES",
"SE",
"CH",
"TR",
"UA",
"GB",
"VA",
]
RegionType
module-attribute
#
RegionType = Union[
UCTERegionType, CGMESRegionType, AllCountriesRegionType
]
LimitAdjustmentParameters
#
Bases: BaseModel
Parameters for the adjustment of limits of special branches.
The new operational limits will be created like this: 1) Compute AC Loadflow 2) new_limit = current_flow * n_0_factor (or n_1_factor) 3) If new_limit > min_increase (=old_limit * n_0_min_increase) new_limit = min_increase 4) If new_limit > old_limit new_limit = old_limit
n_0_factor
class-attribute
instance-attribute
#
The factor for the N-0 current limit. Default is 1.2
n_1_factor
class-attribute
instance-attribute
#
The factor for the N-1 current limit. Default is 1.4
n_0_min_increase
class-attribute
instance-attribute
#
The minimal allowed load increase in percent for the n-0 case. This value multiplied with the current limit gives a lower border for the new limit. This makes sure, that lines that currently are barely loaded can be used at all Default is 5%.
n_1_min_increase
class-attribute
instance-attribute
#
The minimal allowed load increase in percent for the n-1 case. This value multiplied with the current limit gives a lower border for the new limit. This makes sure, that lines that currently are barely loaded can be used at all Default is 5%.
get_parameters_for_case
#
Get the factors for the specific case
| PARAMETER | DESCRIPTION |
|---|---|
case
|
Which case should be returned
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
tuple[PositiveFloat, PositiveFloat]
|
The factor and the minimal increase |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/messages/preprocess/preprocess_commands.py
AreaSettings
#
Bases: BaseModel
Setting related to the areas that are imported
control_area
instance-attribute
#
The area in which switching can take place. Substations from this area will automatically become relevant substations (switchable) except they are below the cutoff voltage. Also lines in this area will become disconnectable.
view_area
instance-attribute
#
The areas in which branches shall be part of the overload computation, i.e. for which regions shall line flows be computed.
nminus1_area
instance-attribute
#
The areas where elements shall be part of the N-1 computation, i.e. which elements to fail.
cutoff_voltage
class-attribute
instance-attribute
#
The cutoff voltage under which to ignore equipment. Equipment that doesn't have at least one end equal or above this nominal voltage will not be part of the reward/nminus1 computation
dso_trafo_factors
class-attribute
instance-attribute
#
If given, the N-0 and N-1 flows across the dso trafos in the specied region will be limited to the current N-0 flows in the unsplit configuration. For each case (n0 or n1) a new operational limit with the name "border_limit_n0"/"border_limit_n1" is added.
dso_trafo_weight
class-attribute
instance-attribute
#
A weight that is used for trafos that leave the n-1 area, to underlying DSOs
border_line_factors
class-attribute
instance-attribute
#
If given, the N-0 and N-1 flows across the border lines leaving or entering the specied region will be limited to the current N-0 flows in the unsplit configuration. For each case (n0 or n1) a new operational limit with the name "border_limit_n0"/"border_limit_n1" is added.
border_line_weight
class-attribute
instance-attribute
#
A weight that is used for lines that leave the n-1 area, to neighbouring TSOs
RelevantStationRules
#
Bases: BaseModel
Rules to determine whether a substation is relevant or not.
min_busbars
class-attribute
instance-attribute
#
The minimum number of busbars a substation must have to be considered relevant.
min_connected_branches
class-attribute
instance-attribute
#
The minimum number of connected branches a substation must have to be considered relevant. This only counts branches (lines, transformers, tie-lines), not injections (generators, loads, shunts, etc.).
min_connected_elements
class-attribute
instance-attribute
#
The minimum number of connected elements a substation must have to be considered relevant. This includes branches and injections (generators, loads, shunts, etc.).
BaseImporterParameters
#
Bases: BaseModel
Parameters that are required to import any data format.
area_settings
instance-attribute
#
Which areas of the grid are to be imported and how to handle boundaries
data_folder
instance-attribute
#
The path where the entry point where the timestep data folder structure starts.
The folder structure is defined in interfaces.folder_structure. This folder is relative to the processed_grid_folder that is configured in the backend/importer. A typical default would be grid_model_file.stem
grid_model_file
instance-attribute
#
The path to the input grid model file.
This file should contain the grid model in the format defined by the data_type. For instance a .uct for UCTE data or a .zip for CGMES data.
data_type
instance-attribute
#
The type of data that is being imported.
This will determine the importer that is used to load the data.
white_list_file
class-attribute
instance-attribute
#
The path to the white lists if present
black_list_file
class-attribute
instance-attribute
#
The path to the balck lists if present
ignore_list_file
class-attribute
instance-attribute
#
The path to the ignore lists if present
A csv file with the following columns: grid_model_id, reason
The implementation is expected to ignore all elements that are in the ignore list.
select_by_voltage_level_id_list
class-attribute
instance-attribute
#
If given, only the voltage levels in this list will be imported. Note: not all voltage levels in this list might be considered relevant after preprocessing. This can happen if the requirements for relevant substations are not met. E.g. minimum number of busbars, connected branches or missing busbar couplers.
ingress_id
class-attribute
instance-attribute
#
An optional id that is used to identify the source of the data. This can be used to track where the data came from, e.g. if it was imported from a specific database or a specific user.
contingency_list_file
class-attribute
instance-attribute
#
The path to the contingency lists if present expected format see: importer/contingency_from_power_factory/PF_data_class.py
schema_format
class-attribute
instance-attribute
#
The schema format of the contingency list file if present. This can be either "ContingencyImportSchemaPowerFactory" or "ContingencyImportSchema". found in: - importer/contingency_from_power_factory/PF_data_class.py - importer/pypowsybl_import/contingency_from_file/contingency_file_models.py
relevant_station_rules
class-attribute
instance-attribute
#
relevant_station_rules = RelevantStationRules()
Rules to determine whether a substation is relevant or not.
UcteImporterParameters
#
Bases: BaseImporterParameters
Parameters that are required to import the data from a UCTE file.
This will utilize powsybl and the powsybl backend to the loadflow solver
area_settings
class-attribute
instance-attribute
#
area_settings = AreaSettings(
control_area=["D8"],
view_area=["D2", "D4", "D7", "D8"],
nminus1_area=["D2", "D4", "D7", "D8"],
)
By default the D8 is controllable and the german grid is viewable
grid_model_file
instance-attribute
#
The path to the UCTE file to load. Note that only a single timestep, i.e. only a single UCTE file will be loaded in one import/preprocessing run. For multiple timesteps, the preprocessing is triggered multiple times.
data_type
class-attribute
instance-attribute
#
A constant field to indicate that this is a UCTE importer
data_folder
instance-attribute
#
The path where the entry point where the timestep data folder structure starts.
The folder structure is defined in interfaces.folder_structure. This folder is relative to the processed_grid_folder that is configured in the backend/importer. A typical default would be grid_model_file.stem
white_list_file
class-attribute
instance-attribute
#
The path to the white lists if present
black_list_file
class-attribute
instance-attribute
#
The path to the balck lists if present
ignore_list_file
class-attribute
instance-attribute
#
The path to the ignore lists if present
A csv file with the following columns: grid_model_id, reason
The implementation is expected to ignore all elements that are in the ignore list.
select_by_voltage_level_id_list
class-attribute
instance-attribute
#
If given, only the voltage levels in this list will be imported. Note: not all voltage levels in this list might be considered relevant after preprocessing. This can happen if the requirements for relevant substations are not met. E.g. minimum number of busbars, connected branches or missing busbar couplers.
ingress_id
class-attribute
instance-attribute
#
An optional id that is used to identify the source of the data. This can be used to track where the data came from, e.g. if it was imported from a specific database or a specific user.
contingency_list_file
class-attribute
instance-attribute
#
The path to the contingency lists if present expected format see: importer/contingency_from_power_factory/PF_data_class.py
schema_format
class-attribute
instance-attribute
#
The schema format of the contingency list file if present. This can be either "ContingencyImportSchemaPowerFactory" or "ContingencyImportSchema". found in: - importer/contingency_from_power_factory/PF_data_class.py - importer/pypowsybl_import/contingency_from_file/contingency_file_models.py
relevant_station_rules
class-attribute
instance-attribute
#
relevant_station_rules = RelevantStationRules()
Rules to determine whether a substation is relevant or not.
CgmesImporterParameters
#
Bases: BaseImporterParameters
Parameters to start an import data from a CGMES file.
This will utilize powsybl and the powsybl backend to the loadflow solver.
area_settings
class-attribute
instance-attribute
#
area_settings = AreaSettings(
control_area=["BE"],
view_area=["BE", "LU", "D4", "D2", "NL", "FR"],
nminus1_area=["BE"],
cutoff_voltage=220,
)
The area settings for the CGMES importer
grid_model_file
instance-attribute
#
The path to the CGMES .zip file to load.
Note that only a single timestep, i.e. only a single CGMES .zip file will be loaded in one import/preprocessing run. For multiple timesteps, the preprocessing is triggered multiple times. Note: the .zip file must contain all xml files in the same root folder, i.e. the following files: - EQ.xml - SSH.xml - SV.xml - TP.xml - EQBD.xml - TPBD.xml
data_type
class-attribute
instance-attribute
#
A constant field to indicate that this is a CGMES importer
data_folder
instance-attribute
#
The path where the entry point where the timestep data folder structure starts.
The folder structure is defined in interfaces.folder_structure. This folder is relative to the processed_grid_folder that is configured in the backend/importer. A typical default would be grid_model_file.stem
white_list_file
class-attribute
instance-attribute
#
The path to the white lists if present
black_list_file
class-attribute
instance-attribute
#
The path to the balck lists if present
ignore_list_file
class-attribute
instance-attribute
#
The path to the ignore lists if present
A csv file with the following columns: grid_model_id, reason
The implementation is expected to ignore all elements that are in the ignore list.
select_by_voltage_level_id_list
class-attribute
instance-attribute
#
If given, only the voltage levels in this list will be imported. Note: not all voltage levels in this list might be considered relevant after preprocessing. This can happen if the requirements for relevant substations are not met. E.g. minimum number of busbars, connected branches or missing busbar couplers.
ingress_id
class-attribute
instance-attribute
#
An optional id that is used to identify the source of the data. This can be used to track where the data came from, e.g. if it was imported from a specific database or a specific user.
contingency_list_file
class-attribute
instance-attribute
#
The path to the contingency lists if present expected format see: importer/contingency_from_power_factory/PF_data_class.py
schema_format
class-attribute
instance-attribute
#
The schema format of the contingency list file if present. This can be either "ContingencyImportSchemaPowerFactory" or "ContingencyImportSchema". found in: - importer/contingency_from_power_factory/PF_data_class.py - importer/pypowsybl_import/contingency_from_file/contingency_file_models.py
relevant_station_rules
class-attribute
instance-attribute
#
relevant_station_rules = RelevantStationRules()
Rules to determine whether a substation is relevant or not.
ReassignmentLimits
#
Bases: BaseModel
Reassignment limits for electrical reconfiguration at substations.
max_reassignments_per_sub
class-attribute
instance-attribute
#
The maximum number of reassignments to perform during the electrical reconfiguration. Gets overriden by station_specific_limits if an station id is given.
station_specific_limits
class-attribute
instance-attribute
#
Specific reassignment limits per station to override the global reassignment limit. Expects a grid model id as key and the maximum number of reassignments as value. Note: the grid model id must match the id in the relevant substation list after import.
PreprocessParameters
#
Bases: BaseModel
Parameters for the preprocessing procedure which is independent of the data source
filter_disconnectable_branches_processes
class-attribute
instance-attribute
#
When checking for disconnectable branches, multiple worker processes can be used as it is a costly operation.
action_set_filter_bridge_lookup
class-attribute
instance-attribute
#
Whether to filter the action set using bridge lookups. This will remove all assignments that have less than two non-bridges on every side
action_set_filter_bsdf_lodf
class-attribute
instance-attribute
#
Whether to filter the action set using a consecutive BSDF/LODF application. This will filter out all actions that are also filtered by bridge lookup and additionally all actions that split the grid under N-1 branch outages, i.e. all assignments that created a new bridge in the graph. This is a relatively costly process to run, only set to true if you can afford the extra preprocessing time.
action_set_filter_bsdf_lodf_batch_size
class-attribute
instance-attribute
#
If filtering with bsdf/lodf - which batch size to use. Larger will use more memory but be faster.
action_set_clip
class-attribute
instance-attribute
#
After which size to randomly subselect actions at a substation. If a substations has a lot of branches, the action space will explode exponentially and a safe-guard is to clip after a certain number of actions.
asset_topo_close_couplers
class-attribute
instance-attribute
#
Whether to close open couplers in all stations in the asset topology. This might accidentally cancel a maintenance
separation_set_clip_hamming_distance
class-attribute
instance-attribute
#
If a large configuration table comes out of a substation, the table size can be reduced by removing configurations that are close to each other. This parameter sets the definition of close in terms of hamming distance, by default 0 (no reduction).
separation_set_clip_at_size
class-attribute
instance-attribute
#
By what size a table is considered large. If the table is larger than this size, the clip_hamming_distance will be used to reduce the table size, by default 100. If a table is smaller, no reduction will be applied.
realise_station_busbar_choice_heuristic
class-attribute
instance-attribute
#
The heuristic to use when there are multiple physical busbars available for an asset. The options are: - "first": Use the first busbar in the list of busbars (fastest preprocessing) - "least_connected_busbar": Use the busbar with the least number of connections to other assets (best results)
The "least_connected_busbar" heuristic is the default and is recommended for most cases, trying to spread the assets evenly across the busbars in a station.
electrical_reassignment_limits
class-attribute
instance-attribute
#
If given, limits for the electrical reassignment at substations.
physical_reassignment_limits
class-attribute
instance-attribute
#
If given, limits for the physical reassignment at substations.
ac_dc_interpolation
class-attribute
instance-attribute
#
Whether to use the DC loadflow as the base loadflow (0) or the AC loadflow (1). Can also be anything in between.
n_2_more_splits_penalty
class-attribute
instance-attribute
#
How to penalize additional splits in N-2 that were not there in the unsplit grid. Will be added to the overload energy penalty.
enable_bb_outage
class-attribute
instance-attribute
#
Whether to enable busbar outage analysis
bb_outage_as_nminus1
class-attribute
instance-attribute
#
Whether to treat busbar outages as N-1 outages. If set to False, the busbar outage will be treated similar to N-2 outages. This will be used to compute the busbar outage penalty.
bb_outage_more_splits_penalty
class-attribute
instance-attribute
#
How to penalize additional splits in busbar outages that were not there in the unsplit grid. Will be added to the overload energy penalty.
enable_nodal_inj_optim
class-attribute
instance-attribute
#
Whether to enable nodal injection optimization (including PST optimization)
precision_percent
class-attribute
instance-attribute
#
The precision percent for the nodal injection optimization.
clip_bb_outage_penalty
class-attribute
instance-attribute
#
Whether to clip the lower bound of the busbar outage penalty to 0. We set this parameter to False, if we want the optimiser to solve busbar outage problems in the grid. However, when we just want to ensure that the busbar outage problems are not exacerbated due to the optimiser, we set this to True.
double_limit_n0
class-attribute
instance-attribute
#
If passed, then double limits will be computed for the N-0 flows. Lines that are below double_limit_n0 relative load in the unsplit configuration will have their capacity multiplied by double_limit_n0 to prevent loading them up to their maximum capacity.
double_limit_n1
class-attribute
instance-attribute
#
If passed, then double limits will be computed for the N-1 flows. Lines that are below double_limit_n1 relative load in the unsplit configuration will have their capacities multiplied by double_limit_n1 to prevent loading them up to their maximum capacity.
initial_loadflow_processes
class-attribute
instance-attribute
#
How many processes to use to compute the initial AC loadflow
StartPreprocessingCommand
#
Bases: BaseModel
A command to launch a preprocessing run of a timestep upon reception.
importer_parameters
class-attribute
instance-attribute
#
The parameters to the importer, depending which input source was chosen
preprocess_parameters
class-attribute
instance-attribute
#
preprocess_parameters = PreprocessParameters()
Parameters required for preprocessing independent of the data source
preprocess_id
instance-attribute
#
The id of the preprocessing run, should be included in all responses to identify where the data came from
ShutdownCommand
#
Command
#
Bases: BaseModel
A wrapper to aid deserialization
toop_engine_interfaces.messages.preprocess.preprocess_heartbeat
#
Contains the message classes for a preprocessing worker's heartbeat messages
ConvertToJaxStage
module-attribute
#
ConvertToJaxStage = Literal[
"convert_to_jax_started",
"convert_tot_stat",
"convert_relevant_inj",
"convert_masks",
"switching_distance_info",
"pad_out_branch_actions",
"convert_rel_bb_outage_data",
"create_static_information",
"filter_branch_actions",
"unsplit_n2_analysis",
"bb_outage_baseline_analysis",
"convert_to_jax_done",
]
NumpyPreprocessStage
module-attribute
#
NumpyPreprocessStage = Literal[
"preprocess_started",
"extract_network_data_from_interface",
"filter_relevant_nodes",
"assert_network_data",
"compute_ptdf_if_not_given",
"compute_psdf_if_not_given",
"add_nodal_injections_to_network_data",
"combine_phaseshift_and_injection",
"compute_bridging_branches",
"exclude_bridges_from_outage_masks",
"reduce_branch_dimension",
"reduce_node_dimension",
"filter_disconnectable_branches_nminus2",
"compute_branch_topology_info",
"compute_electrical_actions",
"enumerate_station_realizations",
"remove_relevant_subs_without_actions",
"simplify_asset_topology",
"compute_separation_set",
"convert_multi_outages",
"filter_inactive_injections",
"compute_injection_topology_info",
"process_injection_outages",
"add_missing_asset_topo_info",
"add_bus_b_columns_to_ptdf",
"enumerate_injection_actions",
"preprocess_bb_outage",
"preprocess_done",
]
LoadGridStage
module-attribute
#
LoadGridStage = Literal[
"load_grid_into_loadflow_solver_backend",
"compute_base_loadflows",
"save_artifacts",
]
InitialLoadflowStage
module-attribute
#
ImporterStage
module-attribute
#
ImporterStage = Literal[
"start",
"load_ucte",
"get_topology_model",
"modify_low_impedance_lines",
"modify_branches_over_switches",
"apply_cb_list",
"cross_border_current",
"get_masks",
"end",
]
PreprocessStage
module-attribute
#
PreprocessStage = Literal[
ImporterStage,
NumpyPreprocessStage,
ConvertToJaxStage,
LoadGridStage,
InitialLoadflowStage,
]
PreprocessStatusInfo
#
Bases: BaseModel
A status info to inform about an ongoing preprocess action.
PreprocessHeartbeat
#
Bases: BaseModel
A message class for heartbeats from the preprocessing worker.
When idle, this just sends a hello, and when preprocessing it also conveys a status update at which stage the preprocessing is so it can be tracked in the frontend.
instance_id
class-attribute
instance-attribute
#
The ID of the worker instance that sent this heartbeat.
timestamp
class-attribute
instance-attribute
#
When the heartbeat was sent
uuid
class-attribute
instance-attribute
#
A unique identifier for this heartbeat message, used to avoid duplicates during processing
empty_status_update_fn
#
Log an empty status update to logging.
Use this function when no status_update_fn is provided.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/messages/preprocess/preprocess_heartbeat.py
Loadflow Service#
toop_engine_interfaces.loadflow_results
#
Defines interfaces for loadflow results.
The overall process is that a job is called on a loadflow engine for a grid. The grid holds some information that is referenced in the results: - an N-1 definition, which can include multi-contingencys. An N-1 case is uniquely identified by a string descriptor but can include multiple failing elements. The string identifier of the N-1 case should be delivered upon loading. - a number of timesteps, which are uniquely identified by an integer index. - branches which are uniquely identified by a string descriptor and have either two or three sides. - nodes which are uniquely identified by a string descriptor and have a type (PV, PQ, REF) - regulating elements which are uniquely identified by a string descriptor and have a type (generator, regulating transformer, SVC, ...)
LoadflowResultTable
module-attribute
#
LoadflowResultTable = Union[
DataFrame[NodeResultSchema],
DataFrame[BranchResultSchema],
DataFrame[VADiffResultSchema],
DataFrame[RegulatingElementResultSchema],
DataFrame[ConvergedSchema],
]
BranchSide
#
Bases: Enum
The side of a branch.
ONE
class-attribute
instance-attribute
#
The following side for the types of branches: - line: from side - 2 winding trafo: high voltage side - 3 winding trafo: high voltage side - other: from side
TWO
class-attribute
instance-attribute
#
The following side for the types of branches: - line: to side - 2 winding trafo: low voltage side - 3 winding trafo: medium voltage side - other: to side
THREE
class-attribute
instance-attribute
#
Only valid for 3 winding transformers, representing the low voltage side.
RegulatingElementType
#
Bases: Enum
A list of known regulating elements, TODO expand
GENERATOR_Q
class-attribute
instance-attribute
#
A generator that is used to control the reactive power output.
SLACK_P
class-attribute
instance-attribute
#
The active power output of the slack node.
SLACK_Q
class-attribute
instance-attribute
#
The reactive power output of the slack node.
REGULATING_TRANSFORMER_TAP
class-attribute
instance-attribute
#
A regulating transformer that is used to control the tap position.
SVC_Q
class-attribute
instance-attribute
#
A static var compensator that is used to control the reactive power output.
HVDC_CONVERTER_Q
class-attribute
instance-attribute
#
An HVDC converter station.
OTHER
class-attribute
instance-attribute
#
A placeholder for not yet known regulating elements.
ConvergenceStatus
#
Bases: Enum
The convergence status of the loadflow in a single timestep/contingency/component
FAILED
class-attribute
instance-attribute
#
The loadflow failed to start, e.g. because no slack bus was available
MAX_ITERATION_REACHED
class-attribute
instance-attribute
#
The maximum number of iterations was reached, i.e. the loadflow did not converge.
NO_CALCULATION
class-attribute
instance-attribute
#
The component was ignored due to other reasons (engine did not support it)
BranchResultSchema
#
Bases: DataFrameModel
A schema for the branch results table.
This holds i, p and q values for all monitored branches with a multi-index of timestep, contingency (CO), branch (CB) and side.
If no branches are monitored, this is the empty DataFrame.
TODO Decide if this should be used for injections aswell#
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' without GridElements is used, if its added.
side
class-attribute
instance-attribute
#
side = Field(isin=[(value) for side in BranchSide])
The side of the branch that these results correspond to
i
class-attribute
instance-attribute
#
The current in the branch in A
This should only be NaN if the branch has no connection to the slack bus.
p
class-attribute
instance-attribute
#
The active power in the branch in MW
This should only be NaN if the branch has no connection to the slack bus.
q
class-attribute
instance-attribute
#
The reactive power in the branch in MVar
This should only be NaN if the branch has no connection to the slack bus.
loading
class-attribute
instance-attribute
#
The loading of the branch in % of rated current. This always refers to the permanent/default rating of the branch if there are multiple ratings available. If no rating is available for the branch, this should be set to NaN. If the engine does not support the computation of this value, the column can be omitted.
element_name
class-attribute
instance-attribute
#
The name of the Branch, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
NodeResultSchema
#
Bases: DataFrameModel
A schema for the node results table.
This holds p and q values for all monitored nodes with a multi-index of timestep and contingency. If no nodes are monitored, this is the empty DataFrame.
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' is used.
vm
class-attribute
instance-attribute
#
The voltage magnitude at the node in kV.
In DC, this should be the nominal voltage of the node. This should only be NaN if the node does not have a connection to the slack bus.
vm_loading
class-attribute
instance-attribute
#
How close the voltage magnitude is to the max/min voltage limits in percent. This is computed as: (vm - v_nominal) / (v_max - v_nominal) for vm > v_nominal and (vm - v_nominal) / (v_nominal - v_min) for vm < v_nominal.
va
class-attribute
instance-attribute
#
The voltage angle at the node in degrees
This should only be NaN if the node does not have a connection to the slack bus.
p
class-attribute
instance-attribute
#
The accumulated absolute active power at the node in MW, obtained by summing the absolute active power of all branches and injections connected to the node.
If the engine does not support the computation of this value, the column can be omitted.
q
class-attribute
instance-attribute
#
The accumulated absolute reactive power at the node in MVar, obtained by summing the absolute reactive power of all branches and injections connected to the node
If the engine does not support the computation of this value, the column can be omitted.
element_name
class-attribute
instance-attribute
#
The name of the node, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
VADiffResultSchema
#
Bases: DataFrameModel
A schema for the voltage angle results.
Holds information about the voltage angle difference between busses that could be (re)connected by power switches.
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The critical contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' is used.
element
instance-attribute
#
The element over which the voltage angle difference is computed. Can be either an open switch or any switch or branch under N-1. If under N-1, then element and contingency are the same.
va_diff
class-attribute
instance-attribute
#
The voltage angle difference in degrees between the two ends of the element. nan if at least one of the ends has no voltage angle (island, out of service)
element_name
class-attribute
instance-attribute
#
The name of the Branch or Switch, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
RegulatingElementResultSchema
#
Bases: DataFrameModel
A schema for the regulating elements.
A regulating element can either be a branch (a trafo with regulating tap) or a node (a generator, SVC, ...). If no regulating elements are monitored, this is the empty DataFrame.
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The critical contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' is used.
element
instance-attribute
#
The regulating element that these loadflow results correspond to
value
instance-attribute
#
The value of the regulating element. Depending on the type of the regulating element, this can mean different things.
regulating_element_type
class-attribute
instance-attribute
#
regulating_element_type = Field(
isin=[(value) for side in RegulatingElementType]
)
The type of the regulating element (generator, regulating transformer, SVC, ...).
element_name
class-attribute
instance-attribute
#
The name of the Regulating Element, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
ConvergedSchema
#
Bases: DataFrameModel
A schema for the converged table. This holds the convergence information for each timestep.
Potentially, multiple islands can exist in the same grid. In this case, the synchronous component needs to be distinguished. A synchronous component is a grid area consisting of all nodes and branches that are connected to the same slack through AC lines (no HVDC). The largest component must always be called 'MAIN' while the names of the other components are arbitrary. Usually only one component is present. If no convergence information is available, this is the empty DataFrame.
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The critical contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' is used.
status
class-attribute
instance-attribute
#
status = Field(isin=[(value) for side in ConvergenceStatus])
Whether the loadflow converged at this timestep/contingency.
iteration_count
class-attribute
instance-attribute
#
The number of iterations required for the loadflow to converge.
warnings
class-attribute
instance-attribute
#
An additional string field that carries warnings or error logs for specific timesteps/contingencys/components.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
LoadflowResults
#
Bases: BaseModel
A container for the loadflow results for a computation job.
branch_results
class-attribute
instance-attribute
#
The results for the branches. If no branches are monitored, this is the empty DataFrame. Non converging contingencys/timesteps are to be omitted
node_results
class-attribute
instance-attribute
#
The results for the nodes. If no nodes are monitored, this is the empty DataFrame.
regulating_element_results
class-attribute
instance-attribute
#
The results for the regulating elements. If no regulating elements are monitored, this is the empty DataFrame.
converged
class-attribute
instance-attribute
#
The convergence information for each timestep and contingency. If there were non-converging loadflows for some timesteps/contingencys, these results should be omitted from the other tables.
va_diff_results
class-attribute
instance-attribute
#
The voltage angle difference results for each timestep and contingency. Considers the ends of the outaged branch, aswell as all open switches in monitored elements.
warnings
class-attribute
instance-attribute
#
Global warnings that occured during the computation (e.g. monitored elements/contingencies that were not found)
additional_information
class-attribute
instance-attribute
#
Additional information that the loadflow solver wants to convey to the user. There is no limitation what can be put in here except that it needs to be json serializable.
__eq__
#
Compare two LoadflowResults objects for equality.
Rounds floats to 6 decimal places for comparison. This is necessary because floating point arithmetic can lead to small differences in the results.
Ignores the order of the DataFrames, but checks that the indices are equal.
| PARAMETER | DESCRIPTION |
|---|---|
lf_result
|
The LoadflowResults object to compare with.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the two LoadflowResults objects are equal, False otherwise. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_results.py
349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 | |
toop_engine_interfaces.loadflow_results_polars
#
Defines performance-improved polars versions of the loadflow results.
The loadflow results here mirror what is defined in loadflow_results.py, but use polars dataframes which are faster.
LoadflowResultTablePolars
module-attribute
#
LoadflowResultTablePolars = Union[
LazyFrame[NodeResultSchemaPolars],
LazyFrame[BranchResultSchemaPolars],
LazyFrame[VADiffResultSchemaPolars],
LazyFrame[RegulatingElementResultSchemaPolars],
LazyFrame[ConvergedSchemaPolars],
]
BranchResultSchemaPolars
#
Bases: DataFrameModel, BranchResultSchema
Polars variant of BranchResultSchema.
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' without GridElements is used, if its added.
side
class-attribute
instance-attribute
#
side = Field(isin=[(value) for side in BranchSide])
The side of the branch that these results correspond to
i
class-attribute
instance-attribute
#
The current in the branch in A
This should only be NaN if the branch has no connection to the slack bus.
p
class-attribute
instance-attribute
#
The active power in the branch in MW
This should only be NaN if the branch has no connection to the slack bus.
q
class-attribute
instance-attribute
#
The reactive power in the branch in MVar
This should only be NaN if the branch has no connection to the slack bus.
loading
class-attribute
instance-attribute
#
The loading of the branch in % of rated current. This always refers to the permanent/default rating of the branch if there are multiple ratings available. If no rating is available for the branch, this should be set to NaN. If the engine does not support the computation of this value, the column can be omitted.
element_name
class-attribute
instance-attribute
#
The name of the Branch, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
NodeResultSchemaPolars
#
Bases: DataFrameModel, NodeResultSchema
Polars variant of NodeResultSchema.
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' is used.
vm
class-attribute
instance-attribute
#
The voltage magnitude at the node in kV.
In DC, this should be the nominal voltage of the node. This should only be NaN if the node does not have a connection to the slack bus.
vm_loading
class-attribute
instance-attribute
#
How close the voltage magnitude is to the max/min voltage limits in percent. This is computed as: (vm - v_nominal) / (v_max - v_nominal) for vm > v_nominal and (vm - v_nominal) / (v_nominal - v_min) for vm < v_nominal.
va
class-attribute
instance-attribute
#
The voltage angle at the node in degrees
This should only be NaN if the node does not have a connection to the slack bus.
p
class-attribute
instance-attribute
#
The accumulated absolute active power at the node in MW, obtained by summing the absolute active power of all branches and injections connected to the node.
If the engine does not support the computation of this value, the column can be omitted.
q
class-attribute
instance-attribute
#
The accumulated absolute reactive power at the node in MVar, obtained by summing the absolute reactive power of all branches and injections connected to the node
If the engine does not support the computation of this value, the column can be omitted.
element_name
class-attribute
instance-attribute
#
The name of the node, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
VADiffResultSchemaPolars
#
Bases: DataFrameModel, VADiffResultSchema
Polars variant of VADiffResultSchema.
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The critical contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' is used.
element
instance-attribute
#
The element over which the voltage angle difference is computed. Can be either an open switch or any switch or branch under N-1. If under N-1, then element and contingency are the same.
va_diff
class-attribute
instance-attribute
#
The voltage angle difference in degrees between the two ends of the element. nan if at least one of the ends has no voltage angle (island, out of service)
element_name
class-attribute
instance-attribute
#
The name of the Branch or Switch, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
RegulatingElementResultSchemaPolars
#
Bases: DataFrameModel, RegulatingElementResultSchema
Polars variant of RegulatingElementResultSchema.
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The critical contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' is used.
element
instance-attribute
#
The regulating element that these loadflow results correspond to
value
instance-attribute
#
The value of the regulating element. Depending on the type of the regulating element, this can mean different things.
regulating_element_type
class-attribute
instance-attribute
#
regulating_element_type = Field(
isin=[(value) for side in RegulatingElementType]
)
The type of the regulating element (generator, regulating transformer, SVC, ...).
element_name
class-attribute
instance-attribute
#
The name of the Regulating Element, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
ConvergedSchemaPolars
#
Bases: DataFrameModel, ConvergedSchema
Polars variant of ConvergedSchema.
timestep
instance-attribute
#
The timestep of this result. This indexes into the timesteps that were loaded
contingency
instance-attribute
#
The critical contingency that caused this loadflow. For N-0 results, the special CO 'BASECASE' is used.
status
class-attribute
instance-attribute
#
status = Field(isin=[(value) for side in ConvergenceStatus])
Whether the loadflow converged at this timestep/contingency.
iteration_count
class-attribute
instance-attribute
#
The number of iterations required for the loadflow to converge.
warnings
class-attribute
instance-attribute
#
An additional string field that carries warnings or error logs for specific timesteps/contingencys/components.
contingency_name
class-attribute
instance-attribute
#
The name of the contingency, if available. This is not used for the loadflow computation, but can be used for display purposes. If no name is available, this should be set to an empty string.
LoadflowResultsPolars
#
Bases: BaseModel
A container for the loadflow results for a computation job.
branch_results
class-attribute
instance-attribute
#
The results for the branches. If no branches are monitored, this is the empty DataFrame. Non converging contingencys/timesteps are to be omitted
node_results
class-attribute
instance-attribute
#
The results for the nodes. If no nodes are monitored, this is the empty DataFrame.
regulating_element_results
class-attribute
instance-attribute
#
The results for the regulating elements. If no regulating elements are monitored, this is the empty DataFrame.
converged
class-attribute
instance-attribute
#
The convergence information for each timestep and contingency. If there were non-converging loadflows for some timesteps/contingencys, these results should be omitted from the other tables.
va_diff_results
class-attribute
instance-attribute
#
The voltage angle difference results for each timestep and contingency. Considers the ends of the outaged branch, aswell as all open switches in monitored elements.
warnings
class-attribute
instance-attribute
#
Global warnings that occured during the computation (e.g. monitored elements/contingencies that were not found)
additional_information
class-attribute
instance-attribute
#
Additional information that the loadflow solver wants to convey to the user. There is no limitation what can be put in here except that it needs to be json serializable.
Config
#
Pydantic configuration for the LoadflowResultsPolars model.
arbitrary_types_allowed
class-attribute
instance-attribute
#
Allow arbitrary types in the model.
__eq__
#
Compare two LoadflowResults objects for equality.
Rounds floats to 6 decimal places for comparison. This is necessary because floating point arithmetic can lead to small differences in the results.
Ignores the order of the DataFrames, but checks that the indices are equal.
Note: This functions is not very efficient and can take up to half a minute for >10Mio rows.
| PARAMETER | DESCRIPTION |
|---|---|
lf_result
|
The LoadflowResults object to compare with.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the two LoadflowResults objects are equal, False otherwise. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_results_polars.py
toop_engine_interfaces.loadflow_result_helpers_polars
#
Loadflow result helpers for polars LazyFrames or DataFrames.
Holds functions to work with the loadflow results interfaces.
save_loadflow_results_polars
#
Save loadflow results to a file in hdf5 format.
| PARAMETER | DESCRIPTION |
|---|---|
fs
|
The filesystem to use to save the results. This can be a local filesystem or an object store like S3 or Azure, using the fsspec library. For writing to local disk, you should use the DirFilesystem to inject a base path like this: Similarly, buckets can be used with the appropriate fsspec filesystem like adbs
TYPE:
|
file_path
|
The file path where to save the results to. This is relative to the base name or bucket defined in the storage
TYPE:
|
loadflows
|
The loadflow results to save.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
StoredLoadflowReference
|
A reference to the stored loadflow results. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers_polars.py
load_loadflow_results_polars
#
Load loadflow results from a StoredLoadflowReference.
| PARAMETER | DESCRIPTION |
|---|---|
fs
|
The filesystem to use to load the results. This can be a local filesystem or an object store like S3 or Azure, using the fsspec library.
TYPE:
|
reference
|
The reference to the stored loadflow results.
TYPE:
|
validate
|
Whether to validate the loaded results against the schemas defined in the interfaces. For dataframes with a lot of data this can take a few seconds.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LoadflowResults
|
The loaded loadflow results. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers_polars.py
concatenate_loadflow_results_polars
#
Concatenate the results of the loadflow results.
| PARAMETER | DESCRIPTION |
|---|---|
loadflow_results_list
|
The list of loadflow results to concatenate
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LoadflowResultsPolars
|
The concatenated loadflow results |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers_polars.py
select_timestep_polars
#
Select a single timestep from the loadflow results.
| PARAMETER | DESCRIPTION |
|---|---|
loadflow_results
|
The loadflow results to select the timestep from.
TYPE:
|
timestep
|
The timestep to select.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LoadflowResultsPolars
|
The loadflow results for the selected timestep. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers_polars.py
extract_branch_results_polars
#
extract_branch_results_polars(
branch_results,
timestep,
contingencies,
monitored_branches,
basecase,
)
Extract the branch results for a specific timestep.
| PARAMETER | DESCRIPTION |
|---|---|
branch_results
|
The branch results dataframe to extract the branch results from.
TYPE:
|
timestep
|
The selected timestep to pull from the loadflow results.
TYPE:
|
basecase
|
The basecase contingency id to use for the N-0 results.
TYPE:
|
contingencies
|
The list of contingencies to extract the results for.
TYPE:
|
monitored_branches
|
The list of monitored branches to extract the results for. buses switches etc should not be included here, only branches.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_contingencies n_branches_monitored']
|
The branch results with the following: - shape (n_contingencies, n_branches_monitored) - only the p values of the monitored branches at the from-end - For three winding transformers, the p values are split into three rows for each side (hv, mv, lv). |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers_polars.py
228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 | |
extract_node_matrices_polars
#
extract_node_matrices_polars(
node_results,
timestep,
contingencies,
monitored_nodes,
basecase="BASECASE",
)
Extract the node results for a specific timestep.
| PARAMETER | DESCRIPTION |
|---|---|
node_results
|
The node results polars dataframe to extract the node results from.
TYPE:
|
timestep
|
The selected timestep to pull from the loadflow results.
TYPE:
|
basecase
|
The basecase contingency id to use for the N-0 results.
TYPE:
|
contingencies
|
The list of contingencies to extract the results for.
TYPE:
|
monitored_nodes
|
The list of monitored nodes to extract the results for. buses switches etc should not be included here, only nodes.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
vm_n0
|
The voltage magnitude results for the basecase contingency at the monitored nodes.
TYPE:
|
va_n0
|
The voltage angle results for the basecase contingency at the monitored nodes.
TYPE:
|
vm_n1
|
The voltage magnitude results for the contingencies at the monitored nodes.
TYPE:
|
va_n1
|
The voltage angle results for the contingencies at the monitored nodes.
TYPE:
|
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers_polars.py
extract_solver_matrices_polars
#
Extract the N-0 and N-1 matrices in a similar format to the DC solver.
| PARAMETER | DESCRIPTION |
|---|---|
loadflow_results
|
The loadflow results to extract the matrices from.
TYPE:
|
nminus1_definition
|
The N-1 definition to use for the contingencies and monitored elements.
TYPE:
|
timestep
|
The selected timestep to pull from the loadflow results.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_branches_monitored']
|
The N-0 matrix |
Float[ndarray, ' n_solver_contingencies n_branches_monitored']
|
The N-1 matrix |
Bool[ndarray, ' n_solver_contingencies']
|
The convergence status of the contingencies in the N-1 matrix True if converged or not calculated, False if not converged. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers_polars.py
toop_engine_interfaces.loadflow_result_helpers
#
Loadflow result helpers. Holds functions to work with the loadflow results interfaces.
save_loadflow_results
#
Save loadflow results to a file in hdf5 format.
| PARAMETER | DESCRIPTION |
|---|---|
fs
|
The filesystem to use to save the results. This can be a local filesystem or an object store like S3 or Azure, using the fsspec library. For writing to local disk, you should use the DirFilesystem to inject a base path like this: Similarly, buckets can be used with the appropriate fsspec filesystem like adbs
TYPE:
|
file_path
|
The file path where to save the results to. This is relative to the base name or bucket defined in the storage
TYPE:
|
loadflows
|
The loadflow results to save.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
StoredLoadflowReference
|
A reference to the stored loadflow results. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
load_loadflow_results
#
Load loadflow results from a StoredLoadflowReference.
| PARAMETER | DESCRIPTION |
|---|---|
fs
|
The filesystem to use to load the results. This can be a local filesystem or an object store like S3 or Azure, using the fsspec library.
TYPE:
|
reference
|
The reference to the stored loadflow results.
TYPE:
|
validate
|
Whether to validate the loaded results against the schemas defined in the interfaces. For dataframes with a lot of data this can take a few seconds.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LoadflowResults
|
The loaded loadflow results. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
concatenate_loadflow_results
#
Concatenate the results of the loadflow results.
| PARAMETER | DESCRIPTION |
|---|---|
loadflow_results_list
|
The list of loadflow results to concatenate
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LoadflowResults
|
The concatenated loadflow results |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
get_failed_branch_results
#
get_failed_branch_results(
timestep,
failed_outages,
monitored_2_end_branches,
monitored_3_end_branches,
)
Get the failed branch results.
| PARAMETER | DESCRIPTION |
|---|---|
timestep
|
The timestep of the results
TYPE:
|
failed_outages
|
The list of failed outages
TYPE:
|
monitored_2_end_branches
|
The list of monitored 2 end branches. i.e. most branches
TYPE:
|
monitored_3_end_branches
|
The list of monitored 3 end branches. i.e. 3 winding transformers
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DataFrame[BranchResultSchema]
|
The failed branch results |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
get_failed_node_results
#
Get the failed node results.
| PARAMETER | DESCRIPTION |
|---|---|
timestep
|
The timestep of the results
TYPE:
|
failed_outages
|
The list of failed outages
TYPE:
|
monitored_nodes
|
The list of monitored nodes
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DataFrame[NodeResultSchema]
|
The failed node results |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
extract_branch_results
#
Extract the branch results for a specific timestep.
| PARAMETER | DESCRIPTION |
|---|---|
branch_results
|
The branch results dataframe to extract the branch results from.
TYPE:
|
timestep
|
The selected timestep to pull from the loadflow results.
TYPE:
|
basecase
|
The basecase contingency id to use for the N-0 results.
TYPE:
|
contingencies
|
The list of contingencies to extract the results for.
TYPE:
|
monitored_branches
|
The list of monitored branches to extract the results for. buses switches etc should not be included here, only branches.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_contingencies n_branches_monitored']
|
The branch results with the following: - shape (n_contingencies, n_branches_monitored) - only the p values of the monitored branches at the from-end - For three winding transformers, the p values are split into three rows for each side (hv, mv, lv). |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
extract_node_matrices
#
extract_node_matrices(
node_results,
timestep,
contingencies,
monitored_nodes,
basecase="BASECASE",
)
Extract the node results for a specific timestep.
| PARAMETER | DESCRIPTION |
|---|---|
node_results
|
The node results dataframe to extract the node results from.
TYPE:
|
timestep
|
The selected timestep to pull from the loadflow results.
TYPE:
|
basecase
|
The basecase contingency id to use for the N-0 results.
TYPE:
|
contingencies
|
The list of contingencies to extract the results for.
TYPE:
|
monitored_nodes
|
The list of monitored nodes to extract the results for. buses switches etc should not be included here, only nodes.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
vm_n0
|
The voltage magnitude results for the basecase contingency at the monitored nodes.
TYPE:
|
va_n0
|
The voltage angle results for the basecase contingency at the monitored nodes.
TYPE:
|
vm_n1
|
The voltage magnitude results for the contingencies at the monitored nodes.
TYPE:
|
va_n1
|
The voltage angle results for the contingencies at the monitored nodes.
TYPE:
|
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
extract_solver_matrices
#
Extract the N-0 and N-1 matrices in a similar format to the DC solver.
| PARAMETER | DESCRIPTION |
|---|---|
loadflow_results
|
The loadflow results to extract the matrices from.
TYPE:
|
nminus1_definition
|
The N-1 definition to use for the contingencies and monitored elements.
TYPE:
|
timestep
|
The selected timestep to pull from the loadflow results.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Float[ndarray, ' n_branches_monitored']
|
The N-0 matrix |
Float[ndarray, ' n_solver_contingencies n_branches_monitored']
|
The N-1 matrix |
Bool[ndarray, ' n_solver_contingencies']
|
The convergence status of the contingencies in the N-1 matrix True if converged or not calculated, False if not converged. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
select_timestep
#
Select a specific timestep from the loadflow results.
| PARAMETER | DESCRIPTION |
|---|---|
loadflow_results
|
The loadflow results to select the timestep from.
TYPE:
|
timestep
|
The timestep to select.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LoadflowResults
|
The loadflow results for the selected timestep. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
convert_polars_loadflow_results_to_pandas
#
Convert the LoadflowResultsPolars class to LoadflowResults class.
| PARAMETER | DESCRIPTION |
|---|---|
loadflow_results_polars
|
The loadflow results in polars format.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LoadflowResults
|
The loadflow results in pandas format. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
convert_pandas_loadflow_results_to_polars
#
Convert the LoadflowResults class to LoadflowResultsPolars class.
| PARAMETER | DESCRIPTION |
|---|---|
loadflow_results
|
The loadflow results in pandas format.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LoadflowResultsPolars
|
The loadflow results in polars format. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/loadflow_result_helpers.py
toop_engine_interfaces.nminus1_definition
#
The N-1 definition holds monitored and outaged elements for a grid.
This information is not present in the grid models and hence needs to be stored separately to run an N-1 computation. The order of the outages should be the same as in the jax code, where it's hardcoded to the following: - branch outages - multi outage - non-relevant injection outages - relevant injection outages
POWSYBL_SUPPORTED_ID_TYPES
module-attribute
#
PANDAPOWER_SUPPORTED_ID_TYPES
module-attribute
#
ELEMENT_ID_TYPES
module-attribute
#
ELEMENT_ID_TYPES = Literal[
PANDAPOWER_SUPPORTED_ID_TYPES,
POWSYBL_SUPPORTED_ID_TYPES,
]
GridElement
#
Bases: BaseModel
A grid element is identified by its id(powsybl) or its id and type (pandapower)
id
instance-attribute
#
The id of the element. For powsybl grids this is the global string id, for pandapower this is the integer index into the dataframe
name
class-attribute
instance-attribute
#
The name of the element. This is optional, but can be used to provide a more human-readable name for the element.
type
instance-attribute
#
For pandapower, we need to further specify a type which corresponds to the table pandapower stores the information in. Valid tables are 'line', 'trafo', 'ext_grid', 'gen', 'load', 'shunt', ... For powsybl, this is not strictly needed to identify the element however it makes it easier. In that case, type will be something like TIE_LINE, LINE, TWO_WINDING_TRANSFORMER, GENERATOR, etc.
kind
instance-attribute
#
The kind of the element. Usually these are handled differently in the grid modelling software, so it can make assembling an N-1 analysis easier if it is known if the element is a branch, bus or injection. This could be inferred from the type, however for conveniece it is stored separately.
For the bus type there is some potential confusion in powsybl. In pandapower, this always refers to the net.bus df. In powsybl in a bus/branch model, there are no busbar sections in powsybl, i.e. net.get_node_breaker_topology does not deliver busbar sections. Meaning, the "bus" type refers to the net.get_bus_breaker_topology buses if it's a bus/breaker topology bus. If it's a node/breaker topology, then "bus" refers to the busbar section.
Contingency
#
Bases: BaseModel
A single N-1 case
elements
instance-attribute
#
The grid elements that are to be outaged under this contingency. Usually, this will be exactly one element however exceptional contingencies and multi-outages might include more than one element.
id
instance-attribute
#
The id of the contingency. This is used to identify the contingency in the results. It should be unique across all contingencies in the N-1 definition.
name
class-attribute
instance-attribute
#
The name of the contingency. This is optional, but can be used to provide a more human-readable name. This will show up in the Loadflowresult-tables as column contingency_name.
is_multi_outage
#
Check if the contingency is a multi-outage.
A multi-outage is defined as a contingency that has more than one element in it.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/nminus1_definition.py
is_basecase
#
Check if the contingency is the N-0 base case.
A base case is defined as a contingency that has no elements in it.
is_single_outage
#
Check if the contingency is a normal single-element outage.
A single outage is defined as a contingency that has exactly one element in it.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/nminus1_definition.py
LoadflowParameters
#
Bases: BaseModel
Loadflow parameters for the N-1 computation.
distributed_slack
class-attribute
instance-attribute
#
Whether to distribute the slack across all injections in the grid. Only relevant for powsybl grids.
contingency_propagation
class-attribute
instance-attribute
#
Whether to enable powsybl's contingency propagation in the N-1 analysis.
Powsybl: https://powsybl.readthedocs.io/projects/powsybl-open-loadflow/en/latest/security/parameters.html Security Analysis will determine by topological search the switches with type circuit breakers (i.e. capable of opening fault currents) that must be opened to isolate the fault. Depending on the network structure, this could lead to more equipments to be simulated as tripped, because disconnectors and load break switches (i.e., not capable of opening fault currents) are not considered.
Pandapower: Currently not supported in pandapower.
Nminus1Definition
#
Bases: BaseModel
An N-1 definition holds monitored and outaged elements for a grid.
For powsybl, ids are unique across types (i.e. a branch and an injection can not have the same id), however in pandapower, ids are not unique and we have to store the type alongside with them.
monitored_elements
instance-attribute
#
A list of monitored elements that should be observed during the N-1 computation.
contingencies
instance-attribute
#
A list of contingencies that should be computed during the N-1 computation.
loadflow_parameters
class-attribute
instance-attribute
#
loadflow_parameters = Field(
default_factory=LoadflowParameters
)
Loadflow parameters for the N-1 computation.
id_type
class-attribute
instance-attribute
#
The type of the ids used in the N-1 definition. This is used to determine how to interpret the ids in the monitored elements and contingencies. See ELEMENT_ID_TYPES for more information. If none, pandapower will try to use the globally unique ids, and powsybl will use the global string ids.
base_case
property
#
Get the base case contingency, which is the contingency with no elements in it.
__getitem__
#
Get a subset of the nminus1definition based on the contingencies.
If a string is given, the contingency id must be in the contingencies list. If an integer or slice is given, the case id will be indexed by the integer or slice.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/nminus1_definition.py
load_nminus1_definition_fs
#
Load an N-1 definition from a file system.
| PARAMETER | DESCRIPTION |
|---|---|
filesystem
|
The file system to use to load the N-1 definition.
TYPE:
|
file_path
|
The path to the file containing the N-1 definition in json format.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Nminus1Definition
|
The loaded N-1 definition. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/nminus1_definition.py
load_nminus1_definition
#
Load an N-1 definition from a json file
| PARAMETER | DESCRIPTION |
|---|---|
filename
|
The path to the json file containing the N-1 definition.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Nminus1Definition
|
The loaded N-1 definition. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/nminus1_definition.py
save_nminus1_definition
#
Save an N-1 definition to a json file
| PARAMETER | DESCRIPTION |
|---|---|
filename
|
The path to the json file to save the N-1 definition to.
TYPE:
|
nminus1_definition
|
The N-1 definition to save.
TYPE:
|
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/nminus1_definition.py
Asset Topology#
toop_engine_interfaces.asset_topology
#
Contains the data models for the asset topology.
AssetBranchTypePandapower
module-attribute
#
AssetBranchTypePandapower = Literal[
"line",
"trafo",
"trafo3w_lv",
"trafo3w_mv",
"trafo3w_hv",
"impedance",
]
AssetBranchTypePowsybl
module-attribute
#
AssetBranchType
module-attribute
#
AssetBranchType = Literal[
AssetBranchTypePandapower, AssetBranchTypePowsybl
]
AssetInjectionTypePandapower
module-attribute
#
AssetInjectionTypePandapower = Literal[
"ext_grid",
"gen",
"load",
"shunt",
"sgen",
"ward",
"ward_load",
"ward_shunt",
"xward",
"xward_load",
"xward_shunt",
"dcline_from",
"dcline_to",
]
AssetInjectionTypePowsybl
module-attribute
#
AssetInjectionTypePowsybl = Literal[
"LOAD",
"GENERATOR",
"DANGLING_LINE",
"HVDC_CONVERTER_STATION",
"STATIC_VAR_COMPENSATOR",
"SHUNT_COMPENSATOR",
"BATTERY",
]
AssetInjectionType
module-attribute
#
AssetInjectionType = Literal[
AssetInjectionTypePandapower, AssetInjectionTypePowsybl
]
PowsyblSwitchValues
#
Busbar
#
Bases: BaseModel
Busbar data describing a single busbar a station.
grid_model_id
instance-attribute
#
The unique identifier of the busbar. Corresponds to the busbar's id in the grid model.
type
class-attribute
instance-attribute
#
The type of the busbar, might be useful for finding the busbar later on
name
class-attribute
instance-attribute
#
The name of the busbar, might be useful for finding the busbar later on
int_id
instance-attribute
#
Is used to reference busbars in the couplers. Needs to be unique per station
in_service
class-attribute
instance-attribute
#
Whether the busbar is in service. If False, it will be ignored in the switching table
bus_branch_bus_id
class-attribute
instance-attribute
#
The bus_branch_bus_id refers to the bus-branch model bus id. There might be a difference between the busbar grid_model_id (a physical busbar) and the bus_branch_bus_id from the bus-branch model. Use this bus_branch_bus_id to store the bus-branch model bus id. Note: the Station grid_model_id also a bus-branch bus_branch_bus_id. This id is the most splitable bus_branch_bus_id. Other bus_branch_bus_ids are part of the physical station, but are separated by a coupler or branch.
AssetBay
#
Bases: BaseModel
Saves the physical connection from the asset to the substation busbars - a bay (Schaltfeld).
A line usually has three switches, before it is connected to the busbar. Two disconnector switches and one circuit breaker switch. A transformer usually has two switches, before it is connected to the busbar. One disconnector switch and one circuit breaker switch.
type: n - node type: b - busbar (Sammelschiene) type: CB - DV Circuit Breaker / Power Switch (Leistungsschalter) type: DS - Disconnector Switch (Trennschalter)
------------------ busbar 1 - type: b | / type: DS - SR Switch busbar 1 -> used for reassigning the asset to another busbar | ------|----------- busbar 2 - type: b | | / | type: DS - SR Switch busbar 2 -> used for reassigning the asset to another busbar | | --------- bus_3 - type: n - busbar section bus | / type: CB - DV Circuit Breaker / Power Switch -> used for disconnecting the asset from the busbar | --------- bus_2 - type: n - circuit breaker bus | / type: DS - SL Switch (optional) -> not used by the asset | --------- bus_1 - type: n - asset bus ^ | Line/Transformer
sl_switch_grid_model_id
class-attribute
instance-attribute
#
The id of the switch, which connects the asset to the circuit breaker node. This switch is a disconnector switch. Do not use for anything, leave state as found. Default should be closed.
dv_switch_grid_model_id
instance-attribute
#
This switch is a circuit breaker / power switch. Use for disconnecting / reconnecting the asset from the busbar.
sr_switch_grid_model_id
instance-attribute
#
The ids of the switches, which assign the asset to the busbars. key: busbar_grid_model_id e.g. 4%%bus value: sr_switch_grid_model_id This switch is a disconnector switch. Use for reassigning the asset to another busbar. Only one switch should be closed at a time.
check_is_empty
classmethod
#
Check if the dict is empty.
| PARAMETER | DESCRIPTION |
|---|---|
v
|
The dictionary of sr_switch_grid_model_id to check.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, str]
|
The dictionary itself. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If the dictionary is empty. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
BusbarCoupler
#
Bases: BaseModel
Coupler data describing a single coupler at a station.
This references only busbar couplers, i.e. couplers connecting two busbars. Switches connecting assets to a busbar are represented in the asset_switching_table in the station model.
Note: A busbar couple is a physical connection between two busbars, this can be also a cross coupler. To further specify the connection of an asset to a busbar, the asset connection
grid_model_id
instance-attribute
#
The unique identifier of the coupler. Corresponds to the coupler's id in the grid model.
type
class-attribute
instance-attribute
#
The type of the coupler, might be useful for finding the coupler later on
name
class-attribute
instance-attribute
#
The name of the coupler, might be useful for finding the coupler later on
busbar_from_id
instance-attribute
#
Is used to determine where the coupler is connected to the busbars on the "from" side. Refers to the int_id of the busbar
busbar_to_id
instance-attribute
#
Is used to determine where the coupler is connected to the busbars on the "to" side. Refers to the int_id of the busbar
open
instance-attribute
#
The status of the coupler. True if the coupler is open, False if the coupler is closed. TODO: Switch to using the connectivity table instead of this field.
in_service
class-attribute
instance-attribute
#
Whether the coupler is in-service. Out-of-service couplers are assumed to be always open
asset_bay
class-attribute
instance-attribute
#
The asset bay (Schaltfeld) of the coupler. Note: A coupler can have multiple from and to busbars. The asset bay sr_switch_grid_model_id is used save the selector switches of the coupler. Note: A coupler has never a sl_switch_grid_model_id, the dv_switch_grid_model_id should the same as the name of the coupler.
SwitchableAsset
#
Bases: BaseModel
Asset data describing a single asset at a station.
An asset can be for instance a transformer, line, generator, load, shunt. Note: An asset can be connected to multiple busbars through the switching grid, however if this happens a closed coupler between these busbars is assumed. If such couplers are not present, they will be created. Note: An asset that is out-of-service can be represented, but its switching entries will be ignored.
grid_model_id
instance-attribute
#
The unique identifier of the asset. Corresponds to the asset's id in the grid model.
type
class-attribute
instance-attribute
#
The type of the asset. These refer loosely to the types in the pandapower/powsybl grid models. If set, this can be used to disambiguate branches from injections
name
class-attribute
instance-attribute
#
The name of the asset, might be useful for finding the asset later on
in_service
class-attribute
instance-attribute
#
If the element is in service. False means the switching entry for this element will be ignored. This shall not be used for elements intentionally disconnected, instead set all zeros in the switching table.
branch_end
class-attribute
instance-attribute
#
If the asset was a branch, this can store which end of the branch was connected to the station in the original grid model. This can take the values "from", "to", "hv", "mv", "lv", where from/to works for lines and hv/mv/lv works for transformers. This should only be set if this is needed for the postprocessing, in theory a branch should be identifiable by the branch id and the station id. Injection-type assets like generators and loads should not have this set.
asset_bay
class-attribute
instance-attribute
#
The asset bay (Schaltfeld) of the asset. The connection path is used to determine the physical connection of the asset to the busbar. None of these switches will be found in the network model, they are only used for the asset topology.
is_branch
#
Return True if the asset is a branch.
Only works if the type is set. If type is not set this will return None.
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the asset is a branch, False if it is an injection. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
AssetSetpoint
#
Bases: BaseModel
Asset data describing a single asset with a setpoint.
This could for example be a PST or HVDC setpoint. Note: The same asset can both be switchable and have a setpoint. In this case, the asset will be represented twice.
grid_model_id
instance-attribute
#
The unique identifier of the asset. Corresponds to the asset's id in the grid model.
type
class-attribute
instance-attribute
#
The type of the asset, might be useful for finding the asset later on
name
class-attribute
instance-attribute
#
The name of the asset, might be useful for finding the asset later on
Station
#
Bases: BaseModel
Station data describing a single station.
The minimal station model refers to a single bus-brach model bus_id, which contains a splitable bus. A physical representation may have multiple bus-brach model bus_ids.
grid_model_id
instance-attribute
#
The unique identifier of the station. Corresponds to the stations's id in the grid model. Expects the bus-branch model bus_id, which is the most splitable bus_id.
voltage_level
class-attribute
instance-attribute
#
The voltage level of the station.
busbars
instance-attribute
#
The list of busbars at the station. The order of this list is the same order as the busbars in the switching table.
assets
instance-attribute
#
The list of assets at the station. The order of this list is the same order as the assets in the asset_switching_table.
asset_switching_table
instance-attribute
#
Holds the switching of each asset to each busbar, shape (n_bus, n_asset).
An entry is true if the asset is connected to the busbar. Note: An asset can be connected to multiple busbars, in which case a closed coupler is assumed to be present between these busbars Note: An asset can be connected to none of the busbars. In this case, the asset is intentionally disconnected as part of a transmission line switching action. In practice, this usually involves a separate switch from the asset-to-busbar couplers, as each asset usually has a switch that completely disconnects it from the station. These switches are not modelled here, a postprocessing routine needs to do the translation to this physical layout. Do not use in_service for intentional disconnections.
asset_connectivity
class-attribute
instance-attribute
#
Holds the all possible layouts of the asset_switching_table, shape (n_bus, n_asset).
An entry is true if it is possible to connect an asset to the busbar. If None, it is assumed that all branches can be connected to all busbars.
model_log
class-attribute
instance-attribute
#
Holds log messages from the model creation process.
This can be used to store information about the model creation process, e.g. warnings or errors. A potential use case is to inform the user about data quality issues e.g. missing the Asset Bay switches.
check_int_id_unique
classmethod
#
Check if int_id is unique for all busbars.
| PARAMETER | DESCRIPTION |
|---|---|
v
|
The list of busbars to check.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Busbar]
|
The list of busbars. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If int_id is not unique for all busbars. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_coupler_busbars_different
classmethod
#
Check if busbar_from_id and busbar_to_id are different for all couplers.
| PARAMETER | DESCRIPTION |
|---|---|
v
|
The list of couplers to check.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[BusbarCoupler]
|
The list of couplers. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If busbar_from_id and busbar_to_id are the same for any coupler. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_busbar_exists
#
Check if all busbars in couplers exist in the busbars list.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_coupler_references
#
Check if all closed couplers reference in-service busbars.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_asset_switching_table_shape
#
Check if the switching table shape matches the busbars and assets.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_asset_switching_table_current_vs_physical
#
Check all current assignments are physically allowed.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_asset_bay
#
Check if the asset bay bus is in busbars.
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The station itself. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_bus_id
#
Check if station grid_model_id is in the busbar.bus_branch_bus_id.
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The station itself. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
__eq__
#
Check if two stations are equal.
| PARAMETER | DESCRIPTION |
|---|---|
other
|
The other station to compare to.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the stations are equal, False otherwise. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
Topology
#
Bases: BaseModel
Topology data describing a single timestep topology.
A topology includes switchings for substations and potentially asset setpoints.
grid_model_file
class-attribute
instance-attribute
#
The grid model file that represents this timestep. Note that relevant folders might only work on the machine they have been created, so some sort of permanent storage server should be used to keep these files globally accessible
asset_setpoints
class-attribute
instance-attribute
#
The list of asset setpoints in the topology.
timestamp
instance-attribute
#
The timestamp which is represented by this topology during the original optimization. I.e. if this timestep was the 5 o clock timestep on the day that was optimized, then this timestamp would read 5 o clock.
Strategy
#
Bases: BaseModel
Timestep data describing a collection of single timesteps, each represented by a Topology.
author
class-attribute
instance-attribute
#
The author of the strategy, i.e. who has created it.
process_type
class-attribute
instance-attribute
#
The process type that created this topology, e.g. DC-solver, DC+-solver, Human etc.
process_parameters
class-attribute
instance-attribute
#
The process parameters that were used to create this topology.
date_of_creation
class-attribute
instance-attribute
#
The date of creation of this strategy, i.e. when the optimization ran.
metadata
class-attribute
instance-attribute
#
Additional metadata that might be useful for the strategy.
RealizedStation
#
Bases: BaseModel
A realized station, including the new station and the changes made to the original station
reassignment_diff
instance-attribute
#
A list of reassignments that have been made. Each tuple contains the asset index that was affected (not the asset grid_model_id but the index into the asset_switching_table), the busbar index (again the index into the switching table) and whether the asset was connected (True) or disconnected (False) to that busbar.
disconnection_diff
instance-attribute
#
A list of disconnections that have been made. Each tuple contains the asset index that was disconnected.
RealizedTopology
#
Bases: BaseModel
A realized topology, including the new topology and the changes made to the original topology.
This is similar to RealizedStation but holding information for all stations in the topology. The diffs are include a station identifier that shows which station in the topology was affected by the diff.
coupler_diff
instance-attribute
#
A list of couplers that have been switched. Each tuple contains the station grid_model_id and the coupler that was switched.
reassignment_diff
instance-attribute
#
A list of reassignments that have been made. Each tuple contains the station grid_model_id, the asset index that was affected (not the asset grid_model_id but the index into the asset_switching_table), the busbar index (again the index into the switching table) and whether the asset was connected (True) or disconnected (False) to that busbar.
disconnection_diff
instance-attribute
#
A list of disconnections that have been made. Each tuple contains the station grid_model_id and the asset index that was disconnected. This can also include non-relevant stations.
Asset Topology Helper#
toop_engine_interfaces.asset_topology_helpers
#
Collects some common helper functions for asset topology manipulation.
electrical_components
#
Compute the electrical components of a station.
A set of busbars is considered a separate electrical component if it is not connected through a closed coupler to other busbars and there are at least two assets connected to the component.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to analyze.
TYPE:
|
min_num_assets
|
The minimum number of assets connected to a component to be considered a valid component, by default 1
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[list[int]]
|
A list of lists, where each inner list contains the indices of the busbars in the component indexing into the list of all busbars in the station. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
number_of_splits
#
Compute the number of electrical components that are present in a station.
A set of busbars is considered a separate electrical component if it is not connected through a closed coupler to other busbars and there are at least two assets connected to the component.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to analyze.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
int
|
The number of electrical components in the station. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
remove_busbar
#
Remove a busbar with a specific grid_model_id from the station.
This will - remove the busbar from the list of busbars - remove all couplers that are connected to the busbar at either end - remove all asset bay entries that are connected to the busbar - remove the line from the asset switching table - remove the line from the asset connectivity table
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to modify.
TYPE:
|
grid_model_id
|
The grid_model_id of the busbar to remove.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The modified station object with the busbar removed. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
filter_out_of_service_assets
#
Filter out-of-service assets from the station.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to filter.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The new station object with all out-of-service assets removed. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
filter_out_of_service_busbars
#
Filter out-of-service busbars from the station.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to filter.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The new station object with all out-of-service busbars removed. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
filter_out_of_service_couplers
#
Filter out-of-service couplers from the station.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to filter.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The new station object with all out-of-service couplers removed. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
filter_out_of_service
#
Filter out-of-service assets, busbars and couplers from the station.
The return value will be a new station object with all out-of-service elements removed. Note that the busbars are not reindexed, so the busbar ids will be the same as in the original station with missing elements. If you expect a continuous range of busbar ids, you should call reindex_busbars after this function.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to filter.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The new station object with all out-of-service assets removed. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
filter_duplicate_couplers
#
Filter out duplicate couplers
Two couplers are considered duplicates if they connect the same busbars, regardless of their order. If a duplicate coupler is found, only the first one is kept.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to filter.
TYPE:
|
retain_type_hierarchy
|
If provided, not the first coupler is kept but the one with the highest type in the hierarchy list. Highest means that the type is the first in the list. If not provided, the first coupler is kept, by default None
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The new station object with duplicate couplers removed. |
list[BusbarCoupler]
|
The list of removed couplers. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
filter_disconnected_busbars
#
Remove busbars that can not get connected by any coupler.
This creates a graph of the busbars and couplers and returns only the largest connected component. The size of a component is determined by the number of assets connected to it. Open and closed couplers are treated the same if respect_coupler_open is False, i.e. a busbar connected by only open couplers is considered connected. Busbars connected by out-of-service couplers are always considered disconnected.
This also means that elements which are only connected to the disconnected busbars are effectively disconnected, and it looks like they are subject to transmission line switching.
Note that this function does not reindex the busbars, so the busbar ids will be the same as in the original station with missing elements. If you expect a continuous range of busbar ids, you should call reindex_busbars after this function.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object potentially with disconnected busbars.
TYPE:
|
respect_coupler_open
|
If True, only closed couplers are considered connected, if False, all couplers are considered connected, by default False
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The new station object with disconnected busbars removed. |
list[Busbar]
|
The list of removed busbars. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
reindex_busbars
#
Reindex the int-ids of the busbars in the station
This might be necessary after filder_disconnected_busbars or filter_out_of_service have been called.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object with possible inconsistent busbar ids.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The new station object with reindexed busbars, where int-ids are continuous and start at 0. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
filter_assets_by_type
#
Filter assets by type
Removes all assets that have a type which is not in the set of allowed types.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to filter.
TYPE:
|
assets_allowed
|
The set of asset types that are allowed.
TYPE:
|
allow_none_type
|
If True, assets without a type are allowed, by default False
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The new station object with assets of the wrong type removed. |
list[SwitchableAsset]
|
The list of removed assets. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
find_multi_connected_without_coupler
#
Find assets bridging multiple busbars without a coupler in between
These cases can cause a bug in the downstream functions
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to check.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[tuple[int, int, int]]
|
A list of tuples containing the index of the multi-connected asset and the indices of the two busbars it is bridging. Only returns bridges that don't have a coupler in between. The first busbar index will always be lower than the second, hence a routine which always removes the first doesn't run into double removals if an asset appears multiple times. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
fix_multi_connected_without_coupler
#
Remove one connection for multi-connected assets without a coupler in between
Will always remove the connection to the busbar with the lower index.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to fix
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The new station object with the multi-connected assets fixed. |
list[tuple[SwitchableAsset, Busbar, Busbar]]
|
A list of tuples containing the previously multi-connected assets and the busbars they were connected to. The first busbar in the tuple is the one that was disconnected. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
has_transmission_line_switching
#
Check if the switching table contains transmission line switching
Transmission line switching is defined as disconnecting an asset from all busbars on purpose as a remedial action. Out-of-service assets are not considered irrespective of the switching table.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object to check.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the switching table contains transmission line switching, False otherwise. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
find_busbars_for_coupler
#
Find the from and two busbars for a coupler
Finds based on the int_id of the busbars.
| PARAMETER | DESCRIPTION |
|---|---|
busbars
|
The list of busbars to search in
TYPE:
|
coupler
|
The coupler to search for
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Busbar
|
The from busbar |
Busbar
|
The to busbar |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If any of the busbars for the coupler are not found. This should never happen as the station validator should capture such a scenario. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
merge_couplers
#
Merge an updated list of couplers into the original list
Due to preprocessing actions, the new list might contain a subset of the original couplers. Especially duplicate couplers were removed, so if the original list contains duplicates, both couplers need to be switched. It assumes that the busbar ids are mapped through the busbar mapping
If the new list contains duplicates, the couplers are counted as open if all duplicates are open and as closed otherwise
| PARAMETER | DESCRIPTION |
|---|---|
original
|
The original list of couplers of the unprocessed station
TYPE:
|
new
|
The new list of couplers of the processed station after applying the topology
TYPE:
|
busbar_mapping
|
The mapping from the original busbar indices to the new busbar indices
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[BusbarCoupler]
|
The updated list of couplers |
list[BusbarCoupler]
|
The coupler diff in this station, i.e. which couplers have been switched. Stores the new state of the couplers, i.e. which state the coupler has been switched to |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
merge_stations
#
Merge a list of changed stations into a list of original stations
All stations with a grid_model_id that is present in the new list will be updated using merge_station. The coupler+reassignment diffs will be concatenated. If a new station is not present in the original list, it will be appended to the end of the list if missing_station_behavior is "append".
| PARAMETER | DESCRIPTION |
|---|---|
original
|
The original list of stations
TYPE:
|
new
|
The list of changed stations
TYPE:
|
missing_station_behavior
|
What to do if a station is not found in the original list, by default "append"
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Station]
|
The updated list of stations |
list[tuple[str, BusbarCoupler]]
|
The coupler diff that has been switched, consisting of tuples with the station grid_model_id and the coupler that has been switched |
list[tuple[str, int, int, bool]]
|
The reassignment diff that has been switched, consisting of tuples with the station grid_model_id, the asset index that was affected, which busbar index was affected and whether the asset was connected (True) or disconnected (False) to that bus |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
merge_station
#
Merge all the changes from the new station into the original station
This will overwrite all assets, couplers and busbars in the original station with the ones from the new station if the couplers are also found in the new station. Things that are not found in the new station will be left untouched. Assets that are in the new station but not in the original will also be left untouched.
If all in-service elements of original are also in new, then the returned substation will be electrically equivalent to the new substation. If this is not the case, the returned substation has all possible changes applied, but there are cases in which this is not electrically equivalent to the new substation.
You can use asset_topology_helpers.compare_stations to check which elements are different in the two stations and infer the differences.
| PARAMETER | DESCRIPTION |
|---|---|
original
|
The original station that should be modified
TYPE:
|
new
|
The new station that contains the changes that should be merged into the original station
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The modified original station, with all the changes from the new station merged in |
list[BusbarCoupler]
|
The coupler diff that has been switched |
list[tuple[int, int, bool]]
|
The asset diff that has been switched. Each tuple contains the asset index that was affected, which busbar index was affected and whether the asset was connected (True) or disconnected (False) to that bus |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 | |
compare_stations
#
Compare two stations and return the missing elements
It uses grid_model_ids to compare the assets, busbars and couplers. It does not consider different switching states or coupler states, but just checks if all the elements are also in the other station.
| PARAMETER | DESCRIPTION |
|---|---|
a
|
The first station to compare.
TYPE:
|
b
|
The second station to compare.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[BusbarCoupler]
|
The couplers that are in a but not in b. |
list[BusbarCoupler]
|
The couplers that are in b but not in a. |
list[Busbar]
|
The busbars that are in a but not in b. |
list[Busbar]
|
The busbars that are in b but not in a. |
list[SwitchableAsset]
|
The assets that are in a but not in b. |
list[SwitchableAsset]
|
The assets that are in b but not in a. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
load_asset_topology_fs
#
Load an asset topology from a file system.
| PARAMETER | DESCRIPTION |
|---|---|
filesystem
|
The file system to use to load the asset topology.
TYPE:
|
file_path
|
The path to the file containing the asset topology in json format.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Topology
|
The loaded asset topology. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
load_asset_topology
#
Load an asset topology from a file
| PARAMETER | DESCRIPTION |
|---|---|
filename
|
The filename to load the asset topology from
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Topology
|
The loaded asset topology |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
save_asset_topology_fs
#
Save an asset topology to a file system
| PARAMETER | DESCRIPTION |
|---|---|
filesystem
|
The file system to save the asset topology to
TYPE:
|
filename
|
The filename to save the asset topology to
TYPE:
|
asset_topology
|
The asset topology to save
TYPE:
|
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
save_asset_topology
#
Save an asset topology to a file
| PARAMETER | DESCRIPTION |
|---|---|
filename
|
The filename to save the asset topology to
TYPE:
|
asset_topology
|
The asset topology to save
TYPE:
|
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
get_connected_assets
#
Get the assets connected to a specific busbar in a station.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station object containing the switching table and assets.
TYPE:
|
busbar_index
|
The index of the busbar in the switching table.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list of SwitchableAsset
|
A list of assets connected to the specified busbar. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
accumulate_diffs
#
Accumulate the diffs of the realized stations into the format of realized topology
| PARAMETER | DESCRIPTION |
|---|---|
realized_stations
|
The realized stations to accumulate
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[tuple[str, BusbarCoupler]]
|
The accumulated coupler diff |
list[tuple[str, int, int, bool]]
|
The accumulated reassignment diff |
list[tuple[str, int]]
|
The accumulated disconnection diff |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
station_diff
#
Compute the diff between two stations
The same station must be described by both inputs, i.e. the assets, busbars and couplers (except for their open state) must be the same.
| PARAMETER | DESCRIPTION |
|---|---|
start_station
|
The starting station from which to start the diff
TYPE:
|
target_station
|
The ending station to which the diff shall lead when applied to the starting station
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
RealizedStation
|
The realized station containing the target station and the coupler, reassignment and disconnection diffs |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 | |
topology_diff
#
Compute the difference between two topologies
| PARAMETER | DESCRIPTION |
|---|---|
start_topo
|
The starting topology
TYPE:
|
target_topo
|
The targeted topology.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
RealizedTopology
|
The realized topology containing the target topology and the coupler, reassignment and disconnection diffs that lead from the starting topology to the target topology. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
order_station_assets
#
Orders the assets in a station according to a list of asset ids.
If an asset is not found in the station, it will be added to the not_found list. If an asset is not present in the asset_ids list, it will be dropped from the station.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station to order.
TYPE:
|
asset_ids
|
A list of asset ids. The assets will be ordered according to the grid_model_id.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The ordered station |
list[str]
|
A list of asset ids that were not found in the station |
list[str]
|
A list of asset ids that were ignored, i.e. not present in the asset_ids list |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
order_topology
#
Orders the stations in a topology according to a list of ids.
If a station is not found in the topology, it will be added to the not_found list. If a station is not present in the station_ids list, it will be dropped.
| PARAMETER | DESCRIPTION |
|---|---|
topology
|
The topology to order.
TYPE:
|
station_ids
|
A list of station ids. The stations will be ordered according to the grid_model_id.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Topology
|
The ordered topology |
list[str]
|
A list of station ids that were not found in the topology |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
fuse_coupler
#
Fuses a coupler by merging the adjacent busbars into one busbar.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station with the coupler to fuse. Assumes that the coupler is in the station. The open/closed state of the coupler is disregarded, i.e. the coupler will be fused regardless of its state.
TYPE:
|
coupler_grid_model_id
|
The grid_model_id of the coupler to fuse
TYPE:
|
copy_info_from
|
Whether the new busbar retains the information (grid_model_id, etc) of the busbar on the from side of the coupler, by default True. If False, the busbar on the to side of the coupler is used.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The station with the coupler fused. The coupler is removed and the busbars are merged. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 | |
fuse_all_couplers_with_type
#
Fuses all couplers of a specific type in a station.
This will also filter all duplicate couplers, as there might be an edge case in which a triangle of busbars is not properly merged otherwise.
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station with the couplers to fuse
TYPE:
|
coupler_type
|
The type of coupler to fuse, will match the coupler.type attribute. If coupler.type is None, it will never match.
TYPE:
|
copy_info_from
|
Whether the new busbar retains the information (grid_model_id, etc) of the busbar on the from side of the coupler, by default True. If False, the busbar on the to side of the coupler is used.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The station with the couplers fused that matched the type. The couplers are removed and the busbars are merged. |
list[BusbarCoupler]
|
The couplers that were fused or removed due to being parallel and are no longer present in the station. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
find_station_by_id
#
Find a station by its grid_model_id in a list of stations.
| PARAMETER | DESCRIPTION |
|---|---|
stations
|
The list of stations to search in.
TYPE:
|
station_id
|
The grid_model_id of the station to find.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The station with the given grid_model_id. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If the station is not found in the list. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_helpers.py
Asset Topology Loadflow#
toop_engine_interfaces.asset_topology_loadflow
#
Provides an interface for storing loadflow results in the asset topology.
It inherits from the asset_topology interface but adds additional fields for storing loadflow results.
SwitchableAssetWithLF
#
Bases: SwitchableAsset
A switchable asset with additional fields for storing loadflow results.
All fields are optional because json does not support nan/inf values. If a value is nan/inf, it will be converted to None by the field_validtators
i_max
instance-attribute
#
The maximum current allowed over the asset, if present. For assets without a current limit, this is None
grid_model_id
instance-attribute
#
The unique identifier of the asset. Corresponds to the asset's id in the grid model.
type
class-attribute
instance-attribute
#
The type of the asset. These refer loosely to the types in the pandapower/powsybl grid models. If set, this can be used to disambiguate branches from injections
name
class-attribute
instance-attribute
#
The name of the asset, might be useful for finding the asset later on
in_service
class-attribute
instance-attribute
#
If the element is in service. False means the switching entry for this element will be ignored. This shall not be used for elements intentionally disconnected, instead set all zeros in the switching table.
branch_end
class-attribute
instance-attribute
#
If the asset was a branch, this can store which end of the branch was connected to the station in the original grid model. This can take the values "from", "to", "hv", "mv", "lv", where from/to works for lines and hv/mv/lv works for transformers. This should only be set if this is needed for the postprocessing, in theory a branch should be identifiable by the branch id and the station id. Injection-type assets like generators and loads should not have this set.
asset_bay
class-attribute
instance-attribute
#
The asset bay (Schaltfeld) of the asset. The connection path is used to determine the physical connection of the asset to the busbar. None of these switches will be found in the network model, they are only used for the asset topology.
convert_nan
classmethod
#
Replace nan/inf values with None
| PARAMETER | DESCRIPTION |
|---|---|
value
|
The value to check for nan/inf
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Optional[float]
|
The value, or None if it was nan/inf |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_loadflow.py
is_branch
#
Return True if the asset is a branch.
Only works if the type is set. If type is not set this will return None.
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the asset is a branch, False if it is an injection. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
BusbarWithLF
#
Bases: Busbar
A busbar with additional fields for storing loadflow results.
grid_model_id
instance-attribute
#
The unique identifier of the busbar. Corresponds to the busbar's id in the grid model.
type
class-attribute
instance-attribute
#
The type of the busbar, might be useful for finding the busbar later on
name
class-attribute
instance-attribute
#
The name of the busbar, might be useful for finding the busbar later on
int_id
instance-attribute
#
Is used to reference busbars in the couplers. Needs to be unique per station
in_service
class-attribute
instance-attribute
#
Whether the busbar is in service. If False, it will be ignored in the switching table
bus_branch_bus_id
class-attribute
instance-attribute
#
The bus_branch_bus_id refers to the bus-branch model bus id. There might be a difference between the busbar grid_model_id (a physical busbar) and the bus_branch_bus_id from the bus-branch model. Use this bus_branch_bus_id to store the bus-branch model bus id. Note: the Station grid_model_id also a bus-branch bus_branch_bus_id. This id is the most splitable bus_branch_bus_id. Other bus_branch_bus_ids are part of the physical station, but are separated by a coupler or branch.
convert_nan
classmethod
#
Replace nan/inf values with None
| PARAMETER | DESCRIPTION |
|---|---|
value
|
The value to check for nan/inf
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Optional[float]
|
The value, or None if it was nan/inf |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_loadflow.py
StationWithLF
#
Bases: Station
A station with additional fields for storing loadflow results.
busbars
instance-attribute
#
The busbars, overloaded from station replacing the Busbar class with BusbarWithLF
assets
instance-attribute
#
The assets, overloaded from station replacing the SwitchableAsset class with SwitchableAssetWithLF
grid_model_id
instance-attribute
#
The unique identifier of the station. Corresponds to the stations's id in the grid model. Expects the bus-branch model bus_id, which is the most splitable bus_id.
voltage_level
class-attribute
instance-attribute
#
The voltage level of the station.
asset_switching_table
instance-attribute
#
Holds the switching of each asset to each busbar, shape (n_bus, n_asset).
An entry is true if the asset is connected to the busbar. Note: An asset can be connected to multiple busbars, in which case a closed coupler is assumed to be present between these busbars Note: An asset can be connected to none of the busbars. In this case, the asset is intentionally disconnected as part of a transmission line switching action. In practice, this usually involves a separate switch from the asset-to-busbar couplers, as each asset usually has a switch that completely disconnects it from the station. These switches are not modelled here, a postprocessing routine needs to do the translation to this physical layout. Do not use in_service for intentional disconnections.
asset_connectivity
class-attribute
instance-attribute
#
Holds the all possible layouts of the asset_switching_table, shape (n_bus, n_asset).
An entry is true if it is possible to connect an asset to the busbar. If None, it is assumed that all branches can be connected to all busbars.
model_log
class-attribute
instance-attribute
#
Holds log messages from the model creation process.
This can be used to store information about the model creation process, e.g. warnings or errors. A potential use case is to inform the user about data quality issues e.g. missing the Asset Bay switches.
check_int_id_unique
classmethod
#
Check if int_id is unique for all busbars.
| PARAMETER | DESCRIPTION |
|---|---|
v
|
The list of busbars to check.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Busbar]
|
The list of busbars. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If int_id is not unique for all busbars. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_coupler_busbars_different
classmethod
#
Check if busbar_from_id and busbar_to_id are different for all couplers.
| PARAMETER | DESCRIPTION |
|---|---|
v
|
The list of couplers to check.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[BusbarCoupler]
|
The list of couplers. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If busbar_from_id and busbar_to_id are the same for any coupler. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_busbar_exists
#
Check if all busbars in couplers exist in the busbars list.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_coupler_references
#
Check if all closed couplers reference in-service busbars.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_asset_switching_table_shape
#
Check if the switching table shape matches the busbars and assets.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_asset_switching_table_current_vs_physical
#
Check all current assignments are physically allowed.
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_asset_bay
#
Check if the asset bay bus is in busbars.
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The station itself. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
check_bus_id
#
Check if station grid_model_id is in the busbar.bus_branch_bus_id.
| RETURNS | DESCRIPTION |
|---|---|
Station
|
The station itself. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
__eq__
#
Check if two stations are equal.
| PARAMETER | DESCRIPTION |
|---|---|
other
|
The other station to compare to.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the stations are equal, False otherwise. |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology.py
TopologyWithLF
#
Bases: Topology
A topology with additional fields for storing loadflow results.
stations
instance-attribute
#
The stations, overloaded from topology replacing the Station class with StationWithLF
grid_model_file
class-attribute
instance-attribute
#
The grid model file that represents this timestep. Note that relevant folders might only work on the machine they have been created, so some sort of permanent storage server should be used to keep these files globally accessible
asset_setpoints
class-attribute
instance-attribute
#
The list of asset setpoints in the topology.
timestamp
instance-attribute
#
The timestamp which is represented by this topology during the original optimization. I.e. if this timestep was the 5 o clock timestep on the day that was optimized, then this timestamp would read 5 o clock.
map_loadflow_results_station
#
Map loadflow results onto a station without loadflows.
This also converts nan/inf values to None to be compatible with json serialization
| PARAMETER | DESCRIPTION |
|---|---|
station
|
The station to map loadflow results onto, using the plain asset_topology classes
TYPE:
|
node_extractor
|
A function that extracts voltage angle and voltage magnitude for a busbar from some loadflow results table. If any of the values can not be extracted, the extractor is free to return None
TYPE:
|
asset_extractor
|
A function that extracts active power, reactive power, current and maximum current for an asset from some loadflow results table. If any of the values can not be extracted, the extractor is free to return None
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
StationWithLF
|
The station with loadflow results mapped onto it |
Source code in packages/interfaces_pkg/src/toop_engine_interfaces/asset_topology_loadflow.py
113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 | |
map_loadflow_results_topology
#
Map loadflow results onto a topology without loadflows
This also converts nan/inf values to None to be compatible with json serialization
| PARAMETER | DESCRIPTION |
|---|---|
topology
|
The topology to map loadflow results onto, using the plain asset_topology classes
TYPE:
|
node_extractor
|
A function that extracts voltage angle and voltage magnitude for a busbar from some loadflow results table. If any of the values can not be extracted, the extractor is free to return None
TYPE:
|
asset_extractor
|
A function that extracts active power, reactive power, current and maximum current for an asset from some loadflow results table. If any of the values can not be extracted, the extractor is free to return None
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
TopologyWithLF
|
The topology with loadflow results mapped onto it |